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Turbo Debugger is a state-of-the-art, source-level debugger 
designed for Borland Turbo language programmers and pro- 
grammers using other compilers who want a more powerful 
debugging environment. 


Multiple, overlapping windows, a combination of pull-down and 
pop-up menus, and mouse support provide a fast, interactive 
environment. An online context-sensitive help system provides 
you with help during all phases of operation. 


Here are just some of Turbo Debugger’s features: 
muses the expanded memory specification (EMS) for debugging 
large programs 
m full C, Pascal, and assembler expression evaluation 
m reconfigurable screen layout 
w assembler/CPU access when needed. 
a powerful breakpoint and logging facility 
m keystroke recording (macros) 
m back tracing 
™ remote system for debugging large programs 
a support for 80386 and other vendors’ debugging hardware 
a" os support for object-oriented programming in Turbo Pascal 


w full support for C++ in Turbo C++ 
= TSR and device driver debugging 


Hardware and software requirements 


Turbo Debugger runs on the IBM PC family of computers, 
including the XT and AT, the PS/2 series, and all true IBM 
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compatibles. DOS 2.0 or higher is required and at least 384K of 
RAM. It runs on any 80-column monitor, either color or mono- 
chrome. We recommend a hard disk. If you want to run Turbo 
Debugger on a two-floppy system, you must use high-density 
disks. You can also use 3.5-inch, 720K disks; INSTALL won’t 
install Turbo Debugger on these, so you will have to copy the files 
over yourself. 


Turbo Debugger does not require an 8087 math coprocessor chip. 


To use Turbo Debugger with Borland products, you must have 
Turbo Pascal 5.0 or later, Turbo C 2.0, Turbo C++, or Turbo 
Assembler 1.0 or later. You must already have compiled your 
source code into an executable (.EXE file) with full debugging 
information turned on. 


When you run Turbo Debugger, you'll need both the .EXE file and 
the original source files. Turbo Debugger searches for source files 
first in the directory where the compiler found them when it 
compiled, second in the directory specified in the Options/Path 
for Source command, third in the current directory, and fourth in 
the directory the .EXE file is in. 


A note on terminology 


Module 


Function 


Argument 


For convenience and brevity, we use a couple of terms in this 
manual in slightly more generic ways than usual. These terms are 
module, function, and argument. 


Refers to what is usually called a module in C and in assembler, 
but also to what is called a unit in Pascal. 


Refers to both a C function and to what is known in Pascal as a 
subprogram (or routine), which encompasses functions, procedures, 
and object methods. In C, a function can return a value (like a 
Pascal function) or not (like a Pascal procedure). (When a C 
function doesn’t return a value, it’s called a void function.) In the 
interest of brevity, we often use function in a generic way to stand 
for both C functions and Pascal functions and procedures— 
except, of course, in the language-specific areas of the manual. 


Is used interchangeably with parameter in this manual. This 
applies to references to command-line arguments (or parameters), 
as well as to arguments (or parameters) passed to procedures and 
functions. 
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What's in the manual 


Introduction 


Here is a brief synopsis of the chapters and appendixes in this 
manual: 


Chapter 1: Getting started describes the contents of the distri- 
bution disk and tells you how to load Turbo Debugger files into 
your system. It also gives you advice on which chapter to go to 
next, depending on your level of expertise. 


Chapter 2: Debugging and Turbo Debugger explains the Turbo 
Debugger environment, menus, and windows, and shows you 
how to respond to prompts and error messages. 


Chapter 3: A quick example leads you through a sample session—— 
using either a Pascal or C program—that demonstrates many of 
the powerful capabilities of Turbo Debugger. 


Chapter 4: Starting Turbo Debugger shows how to run the 
debugger from the DOS prompt, when to use command-line 
options, and how to record commonly used settings in 
configuration files. 


Chapter 5: Controlling program execution demonstrates the 
various ways of starting and stopping your program, as well as 
how to restart a session or replay the last session. 


Chapter 6: Examining and modifying data explains the unique 
capabilities Turbo Debugger has for examining and changing data 
inside your program. 


Chapter 7: Breakpoints introduces the concept of actions, and 
how they encompass the behavior of what are sometimes referred 
to as breakpoints, watchpoints, and tracepoints. Both conditional 
and unconditional actions are explained, as well as the various 
things that can happen when an action is triggered. 


Chapter 8: Examining and modifying files describes how to 
examine and change program source files, as well as how to 
examine and modify arbitrary disk files, either as text or binary 
data. 


Chapter 9: Expressions describes the syntax of C, Pascal, and 
assembler expressions accepted by the debugger, as well as the 
format control characters used to modify how an expression’s 
value is displayed. 


Chapter 10: C++ and object-oriented Pascal debugging explains 
the debugger's special features that let you examine objects in 
Turbo Pascal 5.5 programs and classes in Turbo C++ programs. 


Chapter 11: Assembler-level debugging explains how to view 
and change memory as raw hex data, how to use the built-in 
assembler and disassembler, and how to examine or modify the 
CPU registers and flags. 


Chapter 12: The 80x87 coprocessor chip and emulator discusses 
how to examine and modify the contents of the floating-point 
hardware or emulator. 


Chapter 13: Command reference is a complete listing of all main 
menu commands and all local menu commands for each window 


type. 


Chapter 14: How to debug a program is an introduction to 
strategies for effective debugging of your programs. 


Chapter 15: Virtual debugging on the 80386 processor describes 
how you can take advantage of the extended memory and power 
of an 80386 computer by letting the program you’re debugging 
use the full address space below 640K, as if no debugger were 
loaded. 


Chapter 16: Protected-mode debugging with TD286 tells you 
how to use TD286 to run Turbo Debugger in protected mode, 
freeing up memory for debugging large programs. 


Chapter 17; Debugging TSRs and device drivers explains how to 
debug terminate and stay resident programs and programs that 
become resident at startup time with Turbo Debugger, and how to 
load a symbol table manually. 


Appendix A: Summary of command-line options is a summary 
of all the command-line options that are completely described in 
Chapter 4. 


Appendix B: Technical notes is for experienced programmers. It 
describes implementation details of Turbo Debugger that explain 
how it interacts with both your program and with DOS. 


Appendix C: Inline assembler keywords lists all instruction 
mnemonics and other special words used for entering inline 
8086 /80286 /80386 and 8087 /80287 /80837 instructions. 
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Appendix D: Customizing Turbo Debugger explains how to use 
the installation program (TDINST) to customize screen colors and 
change default options. 


Appendix E: Remote debugging explains how to use the 
TDREMOTE utility so that you can run Turbo Debugger on one 
system and the program you are debugging on another. 


Appendix F: Dialog boxes and error messages lists all the 
prompts and error messages that can occur, with suggestions on 
how to respond to them. 


Appendix G: Using Turbo Debugger with different languages 
provides several tips when you're debugging programs written in 
C, assembler, or Pascal. 


Glossary is an alphabetical list of commonly used terms in this 
manual, with short definitions. 


How to contact Borland 


Introduction 


408-438-5300 


The best way to contact Borland is to log on to Borland’s Forum 
on CompuServe: Type GO BOR from the main CompuServe menu 
and choose “Borland Programming Forum B (Turbo Prolog, 
Turbo Assembler, Turbo Debugger, & Turbo C)” from the Borland 
main menu. Leave your questions or comments there for the 
support staff to process. 


If you prefer, write a letter with your comments and send it to 


Borland International 

Technical Support Department — Turbo Debugger 
1800 Green Hills Road 

P.O. Box 660001 

Scotts Valley, CA 95066-0001, USA 


You can also telephone our Technical Support department. Please 
have the following information handy before you call: 


1. Product name and serial number on your original distribution 
disk. Please have your serial number ready, or we won't be 
able to process your call. 


2. Product version number. The version number for Turbo 
Debugger is displayed when you first load the program and 
before you press any keys. If you are in Turbo Debugger, 
choose About from the = (System) menu. 


3. Computer brand, model, and the brands and model numbers 
of any additional hardware. 


4, Operating system and version number. (The version number 
can be determined by typing VER at the MS-DOS prompt.) 


5. Contents of your AUTOEXEC.BAT file. 
6. Contents of your CONFIG.SYS file. 


Recommended reading 


Many leading publishers support Borland products with a wide 
range of excellent books, serving everyone from beginning 
programmers to advanced users. Here are a few titles that offer 
additional information on Turbo Debugger and Tools: 


Ackerman, Charles. Turbo Debugger and Tools: A Self-Teaching 
Guide, John Wiley and Sons (New York: 1990). 


Swan, Tom. Mastering Turbo Assembler, Howard W. Sams and Co. 
(Carmel, IN: 1989). 


Swan, Tom. Mastering Turbo Debugger and Tools, Howard W. Sams 
and Co. (Carmel, IN: 1990). 


Syck, Gary. The Waite Group's Turbo Assembler Bible, Howard W. 
Sams and Co. (Carmel, IN: 1990). 
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Chapter 1, Getting started 


Getting started 


Your Turbo Debugger package consists of a set of distribution 
disks and the Turbo Debugger User's Guide (this manual). The 
distribution disks contain all the programs, files, and utilities 
needed to debug programs written in Turbo C, Turbo Assembler, 
Turbo Pascal, and any program written with a Microsoft compiler. 
In the README and the HELPME!.DOC files, the Turbo 
Debugger package also contains documentation on subjects not 
covered in this manual. 


The Turbo Debugger User’s Guide provides a subject-by-subject 
introduction of Turbo Debugger’s capabilities and a complete 
command reference. 


Before you get started using Turbo Debugger, you should make a 
complete working copy of the distribution disks, then store the 
original disks in a safe place. Use the original distribution disks as 
your backup only, and run Turbo Debugger off of the copy you’ve 
just made—the distribution disks are your only backup in case 
anything happens to your working files. 


If you are not familiar with Borland’s no-nonsense license state- 
ment, now’s the time to read the agreement. Mail your filled-in 
product registration card, so you'll be notified about updates and 
new products as they become available. 


The distribution disks 


The README file 


When you install Turbo Debugger on your system, files from the 
distribution disks are copied to your working floppies or to your 
hard disk. Just run INSTALL.EXE, the easy-to-use installation 
program on your distribution disks. The distribution disks are 
formatted for double-sided, double-density disk drives and can be 
read by IBM PCs and close compatibles. 


For a list of the files on your distribution disks, see the README 
file on the Installation disk. 


cy 


It is very important that you take the time to look at the README 
file on the Installation disk before you do anything else with 
Turbo Debugger. This file contains last-minute information that 
may not be in the manual. It also lists every file on the distri- 
bution disks, with a brief description of each. 


To access the README file, insert the Installation disk in drive A, 
switch to drive A by typing A: and pressing Enter, then type README 
and press Enter again. Once you are in README, use the T and 1 
keys to scroll through the file. Press Esc to exit. 


The HELPME!.DOC file 


Your Installation disk also contains a file called HELPME!.DOC, 
which contains answers to problems that users commonly run 
into. Consult it if you find yourself having difficulties. Among 
other things, the HELPME!.DOC file deals with: 

m Screen output for graphics and text-based programs 


w Executing other programs while you are still using the 
debugger 
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a Breaking out of a program 


a The syntactic and parsing differences between Turbo Debugger 
and the Turbo languages 


nu Debugging multi-language programs with Turbo Debugger 


n Tandy 1000A, IBM PC Convertible, or NEC MultiSpeed, and 
other computers that use the NMI (nonmaskable interrupt) 


Turbo Debugger utfilities 


Chapier 1, Getting started 


Your Turbo Debugger package comes with several utility pro- 
grams. Detailed information on these utilities is available on your 
distribution disks. See the README file for how to access this 
disk-based documentation. 


Here is a brief description of each of the Turbo Debugger utilities: 


o The CodeView to Turbo Debugger utility, TDCONVRT.EXE, 
lets you debug C and assembler programs developed with 
Microsoft compilers. 

o The remote file transfer utility, TDRF.EXE, works in conjunction 
with remote debugging and lets you issue basic file- 
maintenance commands to a remote system. 

o The symbol table stripping utility, TDSTRIP.EXE, lets you strip 
the debugging information (the “symbol table”) from your pro- 
grams without relinking. 

o TDPACK.EXE lets you pack the debugging information. 

o TDMAP.EXE appends debugging information to a .MAP file. 


o Finally, TOUMP.EXE is a generic object module and .EXE file 
disassembler program. 


o Additionally, we give you a small TSR program, TDNMI.COM 
that resets the breakout-switch latch if you are using a 
Periscope I board. 


For a list of all the command-line options available for 
TDCONVRT.EXE, TDRF.EXE, TDSTRIP.EXE, TDPACK.EXE, 
TDMAP.EXE, or TDUMP.EXE, just type the program name and 
press Enter. For example, to see the command-line options for 
TDMAP.EXE, you would enter 


TDMAP 


Installing Turbo Debugger 


c> 


Unzipping 
example files 


The Installation disks contain a program called INSTALL.EXE 
that will assist you with the installation of Turbo Debugger 2.0. 


To start the installation, change your current drive to the one that 
has the INSTALL program on it and enter INSTALL. You are given 
instructions in a box at the bottom of the screen for each prompt. 


INSTALL copies all Turbo Debugger files onto your hard disk and 
puts them into subdirectories. The default subdirectories are 


Turbo Debugger directory: C:\TD 
Example subdirectory: C:\TD 


By default, all files from the distribution disks are placed in the 
Turbo Debugger directory. If you would rather separate the demo 
programs into their own subdirectory as well, edit the default 
example files path before selecting START INSTALLATION. 


You should read the README file to get further information 
about Turbo Debugger after you install Turbo Debugger. 


For a list of all the command-line options available for 
INSTALL.EXE, enter the program name followed by -h: 


INSTALL ~h 


The Turbo Debugger distribution disks contain a file with a .ZIP 
file name extension: TDEXAMPL.ZIP. 


These files contain several other files that have been compressed 
and placed inside an archive. You can de-archive them yourself 
by using the UNZIP.EXE utility. 


For example, entering 
UNZIP TDEXAMPL 


unpacks all the files stored in the TDEXAMPL.ZIP archive into 
the current directory. 


INSTALL gives you a choice of copying the .ZIP files intact or de- 
archiving and copying all of the individual files onto your hard 
disk during the installation process. 
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LCD and B/W 
monitors 


If you have difficulty reading the text displayed by the INSTALL 
utility, it accepts an optional /B command-line parameter that 
forces it to use black-and-white (BW80) mode: 


A: INSTALL /B 


Specifying the /B parameter may be necessary if you are using an 
LCD screen or a system that has a color graphics adapter and a 
monochrome or composite monitor. 


Hardware debugging 


Where to now? 


If you’re using an 80386 system, you can install the TDH386.SYS 
device driver supplied with Turbo Debugger. This device driver 
will vastly speed up breakpoints that watch for changed memory 
areas and I/O port accesses. 


Copy this file to the directory where you keep your device drivers 
and put a line in your CONFIG.SYS file that loads the driver, such 
as 


DEVICE = \SYS\TDH386.SYS 


The next time you boot up your system, Turbo Debugger will be 
able to find and use this device driver. 


See the disk-based documentation on the hardware debugger 
interface for complete information on this device driver interface. 


If you have a hardware debugging board (such as Atron, 
Periscope, Purart Trapper, and so on), you may be able to use the 
board with Turbo Debugger. Check with the vendor of your 
board for its compatibility with Turbo Debugger. 


Chapter 1, Getting started 


Now that you've loaded all the files, you can start learning about 
Turbo Debugger. Since this User’s Guide is written for two types of 
users, different chapters of the manual may appeal to you. The 
following roadmap will guide you. 
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Programmers 
learning a Turbo 
language 


Programmers 
already using a 
Turbo language 


If you are just starting to learn one of the languages in the Turbo 
family, you will want to be able to create small programs using it 
before you learn about the debugger. What better way to learn 
how to use the debugger than to have a real live problem of your 
own to debug! After you have gained a working knowledge of the 
language, work your way through Chapter 3, “A quick example,” 
for a speedy tour of the major functions of Turbo Debugger. There 
you'll learn enough about the features you need to debug your 
first program; you'll find out about the debugger’s more 
sophisticated capabilities in later chapters. 


If you are an experienced Turbo family programmer, you can 
learn about the exciting new features of the Turbo Debugger 
environment by reading Chapter 2, “Debugging and Turbo 
Debugger.” If it suits your style, you can then work through the 
tutorial or, if you prefer, move straight on to Chapter 4, “Starting 
Turbo Debugger.” For a complete rundown of all commands, turn 
to Chapter 13, “Command reference.” 
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Debugging and Turbo Debugger 


The simple truth is that no one’s perfect; we all make mistakes. 
Whether it’s with simple things like walking or complicated 
things like programming, we all stumble sometimes. 


If you’re a programmer, stumbling is a way of life. You hardly 
ever write an error-free program the first time out the gate. That’s 
nothing to be ashamed of. Stumbling also implies picking yourself 
up off the floor and trying again, and again, and maybe again. In 
programming parlance, that’s debugging. 


What is debugging? 


Debugging is the process of finding and correcting errors (“bugs”) 
in your programs. It’s not unusual to spend more time on finding 
and fixing bugs in your program than on writing the program in 
the first place. Debugging is not an exact science; the best debug- 
ging tool you have is your own “feel” for where a program has 
gone wrong. Nonetheless, you can always profit from a syste- 
matic method of debugging. 
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The debugging process can be broadly divided into four steps: 


1. Realizing you have an error 
2. Finding where the error is 

3. Finding the cause of the error 
4, Fixing the error 


Is there a bug? 


The first step can be really obvious. The computer freezes up (or 
hangs) whenever you run it. Or perhaps it crashes in a shower of 
meaningless characters. Sometimes, however, the presence of a 
bug is not so obvious. The program might work fine until you 
enter a certain number (like 0 or a negative number) or until you 
examine the output closely. Only then do you notice that the 
result is off by a factor of .2 or that the middle initials in a list of 
names are wrong. 


Where is it? 


The second step is sometimes the hardest: isolating where the 
error occurs. Let’s face it, you simply can’t keep the entire pro- 
gram in your head at one time (unless it’s a very small program 
indeed). Your best approach is to divide and conquer—break up 
the program into parts and debug them separately. Structured 
programming is perfect for this type of debugging. 


What is it? 
The third step, finding the cause of the error, is probably the 
second-hardest part of debugging. Once you’ve discovered where 
the bug is, it’s usually somewhat easier to find out why the pro- 
gram is misbehaving. For example, if you’ve determined the error 
is in a procedure called PrintNames, you have only to examine the 
lines of that procedure instead of the entire program. Even so, the 
error can be elusive and you might need to experiment a bit 
before you succeed in tracking down. 


Fixing it 


The final step is fixing the error. Armed with your knowledge of 
the program language and knowing where the error is, you can 
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See Chapter 14 fora more 
detailed discussion of the 
debugging process. 


squash the bug. Now you run the program again, wait for the 
next error to show up, and start the debugging process again. 


Many times this four-step process is accomplished when you are 
writing the program itself. Syntax errors, for example, prevent 
your programs from compiling until they’re corrected. The 
Borland language products have built-in syntax checkers that 
inform you of these errors and let you fix them on the spot. 


But other errors are more insidious and subtle. They lie in wait 
until you enter a negative number, or they’re so elusive you're 
stymied. That’s where Turbo Debugger comes in. 


What Turbo Debugger can do for you 


Adding a full-feature 
debugger to the compiler 
itself would make it too big. 


You must use a conversion 
utility that we supply before 
you debug a program 
wiitten in a Microsoft 
language. 


With the standalone Turbo Debugger, you have access to a much 
more powerful debugger than exists in your language compiler. 


You can use Turbo Debugger with any program written in C, 
Pascal, or assembly language, either the Borland Turbo languages 
or those from other manufacturers if the compiler generates 
CodeView information. You can also debug any program created 
with another manufacturer's language product, but you'll be 
restricted to debugging on the assembly level—unless CodeView 
information is present. Then you must use the TDCONVRT utility 
described in the documentation on Turbo Debugger utilities on 
your distribution disks. 


Turbo Debugger helps with the two hardest parts of the debug- 
ging process: finding where the error is and finding the cause of 
the error. It does this by slowing down program execution so you 
can examine the state of the program at any given spot. You can 
even test new values in variables to see how they affect your pro- 
gram. With Turbo Debugger, you can perform tracing, stepping, 
viewing, inspecting, changing, and watching. 


Tracing You can execute your program one line at a time. 


Backtracing You can step backward through your executed 
code, reversing the execution as you go. 


Stepping You can execute your program one line at a time 
but step over any procedure or function calls. If 
you're sure your procedures and functions are 
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What Turbo 
Debugger won't 
do 


error-free, stepping over them speeds up 
debugging. 


Viewing You can have Turbo Debugger open a special 
window to show you the state of your program 
from various perspectives: variables, their values, 
breakpoints, the contents of the stack, a log, a 
data file, a source file, CPU code, memory, regis- 
ters, numeric coprocessor information, object or 
class hierarchies, execution history, or program 
output. 


Inspecting You can have Turbo Debugger delve deeper into 
the workings of your program and show you the 
contents of complicated data structures like 


arrays. 

Changing You can replace the current value of a variable, 
either globally or locally, with a value you 
specify. 

Watching You can isolate program variables and keep track 


of their changing values as the program runs. 


You can use these powerful tools to dissect your program into 
discrete chunks, confirming that one chunk works before moving 
to the next. In this way, you can burrow through the program, no 
matter how large or complicated, until you find where that bug is 
hiding. Maybe you'll find there’s a function that inadvertently 
reassigns a value to a variable, or maybe the program gets stuck 
in an endless loop, or maybe it gets pulled into an unfortunate 
recursion. Whatever the problem, Turbo Debugger helps you find 
where it is and what's at fault. 


Turbo Debugger 2.0 has even been enhanced to let you debug 
C++ and object-oriented Pascal programs. It is smart about objects 
and classes, and it correctly handles late binding of virtual 
methods or member functions so that it always executes and 
displays the correct code. 


With all the features built into Turbo Debugger, you might be 
thinking that it’s got it all. In truth, there are at least three things 
Turbo Debugger won't do for you. 
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a Turbo Debugger does not have a built-in editor to change your 
source code. Most programmers have their favorite editor and 
are comfortable with it. You can, however, easily transfer con- 
trol to your text editor by choosing the local Edit command 
from a File window (more on local commands in a minute). 
Turbo Debugger uses the editor you specified with the TDINST 
installation program. Better still, if you have Turbo C++, you 
can use the new Transfer feature to run Turbo Debugger from 
inside the Turbo language’s integrated environment. 

m Turbo Debugger cannot recompile your program for you. You 
need the original program compiler (like Turbo Pascal or Turbo 
C) to do that. 

a Turbo Debugger does not take the place of thinking. When 
you're debugging a program, your greatest asset is simple 
thought. Turbo Debugger is a powerful tool, but if you use it 
mindlessly, it’s unlikely to save you time or effort. 


How Turbo 


Debugger does it Here's the really good news: Turbo Debugger gives you all this 


power and sophistication, and at the same time it’s easy—dare we 
say intuitive—to use. 


Turbo Debugger accomplishes this artful blend of power and ease 
by offering an exciting environment. The next section examines 
the advantages of Turbo Debugger’s revolutionary environment. 


The Turbo Debugger advantage 


Once you start using Turbo Debugger, we think you'll be totally 
addicted to it. Turbo Debugger has been especially designed to be 
as easy and convenient as possible. To this end, Turbo Debugger 
offers you these powerful features: 


Convenient and logical global menus. 


a Context-sensitive local menus throughout the product, which 
practically do away with memorizing and typing commands. 

m Dialog boxes in which you can choose, set, and toggle options 
and type in information. 


w When you need to type, Turbo Debugger keeps a history list of 
the text you've typed in similar situations. You can choose text 
from the history list, edit the text, or type in new text. 
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Menus and 
dialog boxes 


Using the menus 
Getting in 


u Full macro control to speed up series of commands and 
keystrokes. 


uw Convenient, complete window management. 
& Mouse support. 

w Access to several types of online help. 

w Session recording and reverse execution. 


The rest of this chapter discusses these six features of the Turbo 
Debugger environment. 


As with many Borland products, Turbo Debugger has a 
convenient global menu system accessible from a menu bar 
running along the top of the screen. This menu system is always 
available, no matter which of the debugger windows is active (that 
is, has a cursor in it). 


A pull-down menu is available for each item on the menu bar. 
Through the pull-down menus, you can 
execute a command. 


open a pop-up menu. Pop-up menus appear when you choose a 
menu item that is followed by a menu icon (»). 


m open a dialog box. Dialog boxes appear when you choose a 
menu item that is followed by a dialog box icon (...). 


There are four ways you can open the menus on the menu bar: 
u Press F10, use — or < to go to the desired menu, and press 
Enter. 


u Press F10, then press the first letter of the menu name (Spacebar, 
F, V, R, B, D, O, W, H). 

u Press Alt plus the first letter of any menu bar command 
(Spacebar, F, V, R, B, D, O, W, H). For example, wherever you are 
in the system, Alt-F takes you to the File menu. The = (System) 

_ menu opens with Alt-Spacebar. 


uw Click the menu bar command with the mouse. 


Once you are in the global menu system, here is how you move 
around in it: 
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Getting around 


Gna. 


Getting out 
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Use > and < to move from one pull-down menu to another. 
(For example, when you are in the File menu, pressing — takes 
you to the View menu.) 

no Use T and J to scroll through the commands in a specific menu. 

a Use Home and End to go to the first and last menu items, 
respectively. 

o Highlight a menu command and press Enter to move to a 
lower-level (pop-up) menu or dialog box. 

u Click the mouse on a command to move to a lower-level (pop- 
up) menu or dialog box. 


This is how you get out of a menu or the menu system: 


no Press Esc to exit a lower-level menu and return to the previous 
menu. 

o Press Esc in a pull-down menu to leave the menu system and 
return to the active window. 

o Press F10 at any menu level (but not in a dialog box) to leave the 
menu system and return to the active window. 

m Click the active window with the mouse to leave the menu 
system and return to the active window. 


Some menu commands have a shortcut hot key that you press to 
execute them. The hot key appears in the menu to the right of 
these commands. 


Figure 13.1 in Chapter 13 shows the complete pull-down menu 
tree for Turbo Debugger. Table 13.1 on page 192 lists all the hot 
keys. For a summary of all the commands available in Turbo De- 
bugger, refer to Chapter 13. 


Dialog boxes 


Table 2.] 
What goes in a dialog box 


Ll 


The hot key for the OK button 
Is Alt-K. 


Xx] 


[. d 


THISFILE. EXE 


THATFILE. EXE 
TOTHERFL. EXE 


tb 
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Many of Turbo Debugger’s command options are available to you 
in dialog boxes. A dialog box contains one or more of the following 


items: 


Item 


Buttons 


Check boxes 


Radio buttons 


Input boxes 


List boxes 


What it looks like, what it does © 


Buttons are “shadowed” text (on monochrome systems 
they appear in reverse video). If you choose a button, 
Turbo Debugger carries out the related action imme- 
diately. Get out of a dialog box by pressing the button 
marked OK to confirm your choices, or Cancel to cancel 
them. Dialog boxes also contain a Help button that 
brings up online help. 


A check box is an on/off toggle. Choose it to turn the 
option on or off. When a check box option is turned on, 
an X appears in brackets: [X]. 


Radio buttons are multi-setting toggles that come in 
sets: You can choose only one radio button ina set at a 
time. When you do, a bullet appears between the 
parentheses: (¢). 


An input box prompts you to type ina string (the name 
of a file, for example). An input box often has a history 
list associated with it (see the section “History lessons” 
for more on these). 


A list box contains a list of items from which you can 
choose (for example, a list of possible files to open). 


You navigate around dialog boxes by pressing Taband Shift-Tab. 
Within sets of radio buttons, use the arrow keys to change the 
settings. To choose a button, tab to it and press Enter. 


If you have a mouse, it is even easier to get around in a dialog 


box. Just click the item you want to choose. To close the dialog 


box, click the close box in the upper left corner. 


You can also choose items in a dialog box by pressing their hot 
key, the highlighted letter in each command. 
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Knowing where 


YOU're At In addition to the convenient system of Borland pull-down 
menus, the Turbo Debugger advantage consists of a powerful 
feature that lessens confusion by actually reducing the number of 
menus. 


To understand this feature, you must realize that first and fore- 
most, Turbo Debugger is context-sensitive. That means it keeps 
tabs on exactly which window you have open, what text is 
selected, and which subdivision, or pane, of the window your 
cursor is in. In other words, it knows precisely what you're look- 
ing at and where the cursor is when you choose a command. And 
it uses this information when it responds. Let’s take an example to 
illustrate. 


Suppose your Pascal program has a line like this: 
MyCounter[TheGrade] := MyCounter[TheGrade] + 1; 


As you'll discover when you work with Turbo Debugger, getting 
information on data structures is easy; all you do is press Cirl-l, the 
hot key that opens an Inspector window, to inspect it. When the 
cursor is at MyCounter, Turbo Debugger shows you information 
on the contents of the entire array variable. But if you were to 
select (that is, highlight) the whole array name and the index and 
then press Ctri-l, Turbo Debugger knows that you want to inspect 
one member and shows you only that member. 


You can tunnel down to finer and finer program detail in this 
way. Pressing Ctr-| while you're already inspecting an array gives 
you a look at a particular member. 


This sort of context-sensitivity makes Turbo Debugger extremely 
easy to use. It saves you the trouble of memorizing and typing 
complicated strings of menu commands or arcane command-line 
switches. You simply move to the item you want to examine (or 
select it using the Ins key or drag over it with the mouse), and then 
invoke the command (Ctr-I for Inspect, for example). Turbo 
Debugger always does its best on delivering the goods for the 
particular item. 


This context-sensitivity, which makes life easy for the user, also 
makes the task of documenting commands difficult. This is 
because Ctrl-l, for example, in Turbo Debugger does not have a 
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Local menus 


Figure 2.1 
Global vs. local menus 


Global menus 


Local menus 


single result; instead, the outcome of a command depends on where 
your cursor is or what text is selected. 


Another aspect of Turbo Debugger’s context-sensitivity is in its 
use of local menus specific to different windows or panes within 
windows. 


Local menus in Turbo Debugger are tailored to the particular 
window or pane you are in. It’s important not to confuse them 
with global menus. Here is a composite screen shot of both kinds 
of menus (when you’re actually working in Turbo Debugger, 
however, you could never have both types of menus showing at 
the same time): 


‘fegisters : 
ffrecatio processor. 


Hg | jxecution history - 
i! Lierarchy 
fhother 


Compare the following two lists: 
= Global menus are those that you access by pressing F10 and 
using the arrow keys or typing the first letter of the menu name. 


a The global menus are always available from the menu bar, 
visible at the top of the screen. 


a Their contents never change. 

m Some of the menu commands have hot key shortcuts that are 
available from any part of Turbo Debugger. 

m You call up a local menu by pressing Alt-F10 or Ctrl-F10, or by 
clicking the right button on your mouse. 


& The placement and contents of the menu depends on which 
window or pane you are in and where your cursor is. 
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a Contents can vary from one local menu to another. (Even so, 
many of the local commands appear in almost all of the local 
menus, so that there’s a predictable core of commands from one 
to another.) The results of like-named commands can be 
different, however, depending on the context. 


m Every command on a local menu has a hot key shortcut 
consisting of Ctrl plus the highlighted letter in the command. 


Because of this arrangement, a hot key, say Cil-S, might mean 
one thing in one context but quite another in a different context. 
(A core of commands, however, is still consistent across the 
local menus. For example, the Goto command and the Search 
command always do the same thing, even when they are 
invoked from different panes.) 


From a user's standpoint, local menus are a great convenience. All 
possible command choices relevant to the moment are laid out at 
a glance. This prevents you from trying to choose inappropriate 
commands and keeps the menus small and uncluttered. 


History lessons 


Menus and context-sensitivity comprise just two aspects of the 
convenient environment of Turbo Debugger. Another habit- 
forming feature is the history list. 


Conforming to the philosophy that the user shouldn’t have to 
type more than absolutely necessary, Turbo Debugger remembers 
whatever you enter into input boxes and displays that text when- 
ever you call up the box again. 


For example, to search for the function called MyPercentage, you 
have to type in all or part of that word. Then suppose you search 
for a variable called ReturnOnInvestment. When you see the dialog 
box this time, you'll notice that ReturnOnInvestment appears in the 
input box. When you search for another text string, both pre- 
viously entered strings appear in the input box. The list keeps 
growing as you continue to use the Search command. 


Chapter 2, Debugging and Turbo Debugger 23 


Figure 2.2 
A history list in an input box 


The first item in a search list is 
always the word the cursor Is 
on in the Module window. 


Automatic name 
completion 


Warning! 
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The search input box might look like this: 


Writeln; 
end; { ParmsOnHeap } 


> begin { progran } 
Init; 


Buffer := GetLine; 

while Buffer = *' do 

begin 

ProcessLine (Buffer); 
a 


etLine 
Numletters 
IsLetter 
Numlines 
Getline 


You can use this history list as a shortcut to typing by using the 
arrow keys to select any previous entry then pressing Enter to start 
the search. If you have a mouse, you can also use the scroll bar to 
scroll to the entry you want. If you use an unaltered entry from 
the history list, that entry is copied to the top of the list. 


You can also edit entries (use the arrow keys to insert the cursor 
in the highlighted text, then edit as usual, using Del or Backspace). 
For example, you can select MyPercentage and change it to 
HisPercentage, instead of typing in the entire text. If you start to 
type a new item when an entry is highlighted, you will overwrite 
the highlighted item. 


A history list lists the last five responses unless you tell it other- 
wise. (You can change its size using the TDINST program.) 


Turbo Debugger keeps a separate history list for most input 
boxes. That way, the text you enter to do a search does not clutter 
up the box for, say, going to a particular label or line number. 


Whenever you are prompted for text entry in an input box, you 
can type in just part of a symbol name in your program, then 
press Ctri-N. 


When the word READY... appears in the upper right corner of the 
screen with three dots after it, it means the symbol table is being 
sorted. Ctrl-N won’t work until the three dots go away, indicating 
that the symbol table is available for name completion. 
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any) 


Incremental 
matching 


Making macros 


Whenever you find yourself 
repeating a series of steps, 
say to yourself, “Shouldn’t | 
be using a macro for this?* 


Create Alt= 
Stop recording Alt- 


Remove 
Delete all 


Window shopping 


o If you have typed enough of a name to uniquely identify it, 
Turbo Debugger simply fills in the rest of it. 


o If the name you have typed so far is not the beginning of any 
known symbol name, nothing happens. 


o If what you have typed matches the beginning of more than 
one symbol name, a list of matching names is presented for you 
to pick the one you want. 


Turbo Debugger also lets you use incremental matching to find 
entries in a dialog box list of file and directory names. Start typing 
the name of the file or directory; if the file is available from the list 
box, the highlight bar moves to the name as soon as you have 
typed enough characters to identify it uniquely. Then all you have 
to do is choose the OK button. 


Macros are simply hot keys that you define. 


You can assign any series of Turbo Debugger commands and 
keystrokes to a single key, for playback whenever you want. 


To create a macro, choose Options | Macros. At this point, you 
have a choice of four commands: Create, Stop Recording, 
Remove, and Delete All. Choose Create; Turbo Debugger prompts 
you for a key to save the upcoming macro to. Press a little-used or 
easily remembered key or key combination (for example, Shift-F1 
for rerunning a program). Now go through all the steps and com- 
mands you want to save to that key. 


To end the macro recording session, do one of these things: 


o Choose Options | Macros | Stop Recording. 
o Press the newly defined macro key (Shiff-F1 in this example). 
o Press Alt- (hold down Altand press the hyphen or minus sign). 


Lots of programs do windows these days, but Turbo Debugger 
does them better. Turbo Debugger displays all information and 
data in menus (local and global), dialog boxes (which you use to 
set options and enter information), and windows. There are many 
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Windows from the View 
menu 


Breakpoints 
Stack 


Log 
Watches 
Variables 


Registers 

Numeric processor 
Execution history 
Hierarchy 
Another 


Chapter 8 details the Module 
window and ifs commanas. 


See Chapter 6 for more 
about the Watches window. 


See Chapter 7 fora 
complete description of this 
type of window and how 
breakpoints work. 
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types of windows; a window's type depends on what sort of 
information it holds. You open and close all windows using menu 
commands (or hot key shortcuts for those commands). Most of 
Turbo Debugger’s windows come from the View menu, which 
lists fourteen types of windows. Another class of window, called 
the Inspector window, is opened by choosing either Data | Inspect 
or Inspect from a local menu. 


Here is a list of the thirteen types of windows that you can open 
from the View menu: 


Once you have opened one or more of these windows, you can 
move, resize, close, and otherwise manage them with commands 
from the Window and = (System) menus, which are discussed in 
the section “Working with windows.” 


Module window 


Displays the program code that you’re debugging. You can move 
around inside the module and examine data and code by posi- 
tioning the cursor on program variable names and issuing the 
appropriate local menu command. 


You will probably spend more time in Module windows than in 
any other type, so take the time to learn about all the various local 
menu commands for this type of window. 


You can also press F3 to open a Module window. 


Watches window 


Displays variables and their changing values. You can add a 
variable to the window by pressing Ctrl-W when the cursor is on 
the variable in the Module window. 


Breakpoints window 


Displays the breakpoints you have set. A breakpoint defines a 
location in your program where execution stops so you can 
examine the program's status. The left pane lists the position of 
every breakpoint (or indicates that it is global), and the right pane 
indicates the conditions under which the currently highlighted 
breakpoint executes. 


Use this window to modify, delete, or add breakpoints. 
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Chapter 5 provides more 
information on the Stack 
window. 


Chapter 7 telis you more 
about the Log window. 


Chapter 5 describes the 
Variables window in more 
detail. 


You can learn more about 
the File window in Chapter 8. 


Stack window 


Displays the current state of the stack, with the function called 
first on the bottom (in C programs, this is function main) and all 
subsequently called functions on top, in the order they were 
called. 


You can bring up and examine the source code of any function in 
the stack by highlighting it and pressing Ctr-l. 


By highlighting a function name in the stack and pressing Cirl-L, 

you open a Variables window displaying variables global to the 
program, variables local to the function, and the arguments with 
which the function was called. 


Log window 


Displays the contents of the message log. The log contains a 
scrolling list of messages and information generated as you work 
in Turbo Debugger. It tells you such things as why your program 
stopped, the results of breakpoints, and the contents of windows 
you saved in the log. 


This window lets you look back into the past and see what led up 
to the current state of affairs. 


Variables window 


Displays all the variables accessible from a given spot in your pro- 
gram. The upper pane has global variables; the lower pane shows 
variables local to the current function or module, if any. 


This window is helpful when you want to find a function or 
variable that you know begins with, say, “abc,” and you can’t 
remember its exact name. You can look in the global Symbol pane 
and quickly find what you want. 


File window 


Displays the contents of a disk file. You can view the file either as 
raw hex bytes or as ASCII text. You can search for specific text or 
byte sequences, as well as directly patching any part of the file on 
disk. 


This is handy if you are debugging a program that uses disk files 
and you want to alter the program's behavior by changing the 
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Chapter II discusses the 


CPU window and assembler- 


level debugging. 


See Chapter 11, which 
discusses assembler 


debugging. for more on this 


window. 


Chapter 11, which discusses 
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assembler debugging, has 
more information on this 
window. 


contents of one of its files. You can also correct a mistake in the 
contents of a file, or examine a file produced by a program to 
make sure the contents are correct. 


CPU window 


Displays the current state of the central processing unit (CPU). 
This window has five panes: one that contains disassembled 
machine instructions, one that shows hex data bytes, one that 
displays a raw stack of hex words, one that lists the contents of 
the CPU registers, and one that indicates the state of the CPU 
flags. 


The CPU window is useful when you want to watch the exact 
sequence of instructions that make up a line of source code or the 
bytes that comprise a data structure. If you know assembler code, 
this can help locate subtle bugs. You do not need to use this 
window to debug the majority of programs. 


Turbo Debugger sometimes opens a CPU window automatically, 
if your program stops on an instruction in the middle of a line of 
source code. 


Dump window 


Displays a raw display of an area of memory. (This window is the 
same as the Data pane of a CPU window.) You can view the data 
as characters, hex bytes, words, double words, or any floating- 
point format. You can use this window to look at some raw data 
when you don’t need to see the rest of the CPU state. The local 
menu has commands to let you modify the displayed data, 
change the format in which you view the data, and manipulate 
blocks of data. 


Registers window 


Displays the contents of the CPU registers and flags. This window 
has two panes, which are the same as the registers pane and flags 
pane, respectively, of a CPU window. Use this window when you 
want to look at the contents of the registers but don’t need to see 
the rest of the CPU state. You can change the value of any of the 
registers or flags through commands in the local menu. 
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Numeric Processor window 


_ _See Chapter 12 formore Displays the current state of the math coprocessor. This window 
information about using the has three panes: one pane that shows the contents of the floating- 
Numeric Processor window. : : 
point registers, one that shows the status flag values, and one that 
shows the control flag values. 


This window can help you diagnose problems in programs that 
use floating-point numbers. You need to have a fair understand- 
ing of the inner workings of the math coprocessor in order to 
really reap the benefits of this window. 


Execution History window 


See Chapter5 formore Displays assembly code and source lines for your program, up to 
inrormaton ee mend the last line executed. The upper pane contains the assembly code 
m "that has been executed, so you can reverse back through it; the 
lower pane displays 


1. whether you are tracing or stepping 
2. the line of source code for the instruction about to be executed 
3. the line number of the source code 


You can examine it or use it to rerun your program to a particular 
spot. 


Hierarchy window 


Lists and displays a hierarchy tree of all object or class types used 
by the current module. The window has two panes: one for the 
object/class type list, the other for the object/class hierarchy tree. 
(If you're debugging a C++ program with multiple inheritance, a 
third pane also opens, showing the parents of the highlighted 
class type.) 


__ See Chapter 10 formore This window shows you the relationship of the objects or classes 
or ie eta ct Aid used by the current module. It also makes it possible for you to 
t "examine any object or class type, as well as its component data 
fields or members, and its methods or member functions, via its 
local menus. 
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Module... 
Dump 
File. ee 


User screen 


Alt-F5 is the hot key that 
toggles between the 
environment and the User 
screen. 


Inspector windows 


Se 


o> 


Duplicate windows 


You can also open duplicates of three types of windows—Dump, 
File, and Module—by choosing View | Another. This lets you keep 
track of several separate areas of assembly code, different files the 
program uses or generates, or several distinct program modules 
at once. 


Don’t be alarmed if Turbo Debugger opens one of these windows 
all by itself. It will do this in some cases in response to a com- 
mand. 


The User screen shows your program’s full output screen. The 
screen you see is exactly the same as the one you would see if 
your program was running directly from DOS and not under 
Turbo Debugger. 


You can use this screen to check that your program is at the place 
in your code that you expect it to be, as well as to verify that it is 
displaying what you want on the screen. To switch to the User 
screen, choose Window | User Screen. After viewing the User 
screen, press any key to go back to the debugger screen. 


An Inspector window displays the current value of a selected 
variable. Open it by choosing Data | Inspect or Inspect from a local 
menu. Usually, you close this window by pressing Esc or clicking 
the close box with the mouse. If you’ve opened more than one 
Inspector window in succession, as often happens when you 
examine a complex data structure, you can remove all the Inspec- 
tor windows by pressing Alt-F3 or using the Window | Close 
command. 


You can open an Inspector window to look at an array of items or 
at the contents of a variable or expression. The number of panes in 
the window depends on the nature of the data you are inspecting. 
An Inspector window adapts to the type of data being displayed. 
It can display not only simple scalars (int, float, and so on), but 
also pointers, arrays, records, structures, and unions. Each type of 
data item is displayed in a way that closely mimics the way you 
are used to seeing it in your program’s source code. 


You create additional Inspector windows simply by choosing the 
Inspect command, whereas you can create additional Module, 
File, or CPU windows only by choosing View | Another. 
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The active window | Even though you can have many windows open in Turbo Debug- 
ger at the same time, only one window can be active. You can spot 
the active window by the following criteria: 


a The active window has a double outline around it, not a single 
line. 
a The active window contains the cursor or highlight bar. 
o If your windows are overlapping, the active window is the 
topmost one. 
When you issue commands, enter text, or scroll, you affect only 
the active window, not any other windows that are open. 


Figure 2.3 
Can you spot the active 
window? 


{=]=Dump 
ds:0000 CD 20 00 AO 
ds:0008 A4 02 D3 0 


1 
ds:0010 C5 41 8D 02 
ds:0018 01 01 mi on a8 


ParmsOnHeaps 
end. 


What's in a window _ A window always has most or all of the following features, which 
give you information about it or let you do things to it: 
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Figure 2.4 
A typical window 
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Zoom and 
Window Iconize 
lose box Title nusber boxes 


+ o¢ 
=[s]=Module: TCDEMO File: tcdemo.c patna |e 31 1=[1] (= 
static void showargs(int argc, char *argv[J 


I progran entry point 


I> int main(int argc, char **argv) { 
unsigned int nlines, nwords, wordcount; 
unsigned long totalcharacters; 


niines = 0; 

nwords = 0; = ¢ Scroll bar 
totalcharacters = M . 

os Ua ar 


while ofan res are I= 0) { 
erordcount - Gee nor ee eneeLs 


Serol] bar seslsy bak 
w An outline (double if the window is active, single otherwise). 
m A title, located at the left top. 


m A scroll bar or bars on the right or bottom if the window opens 
on more information than it can hold at one time. You operate 
the scroll bars with the mouse: 


e Click the direction arrows at the ends of the bar to move one 
line or one character in the indicated direction. 


e Click the gray area in the middle of the bar to move one 
window size in the indicated direction. 


e Drag the scroll box to move as much as you want in the 
direction you want. 


a A resize box in the lower right corner. Drag this with your 
mouse to make the window larger or smaller. 


= A window number in the upper right, reflecting the order in 
which the window was opened. 


u A zoom box and iconize box in the upper right corner. The one 
on the left contains the zoom icon, the one on the right the 
iconize icon. Click these with your mouse to expand the 
window to full screen size, restore it to its original size, or 
iconize it. (When a window is zoomed to full size, only the 
iconize box is available, and when it is iconized, only the zoom 
box is available.) 


m A close box in the upper left corner. Click it with your mouse to 
close the window. 


Turbo Debugger User's Guide 


Working with windows With all these different windows to work with, you will probably 
have several open onscreen at a time. Turbo Debugger makes it 
easy for you to move from one window to another, move them 
around, pile them on top of one another, shrink them to get them 
out of your way, expand them to work in them more easily, and 
close them when you are through. 


Press AltSpacebarto openthe Most of the window-management commands are in the Windows 
= menu, or AltW fo open the ~~ menu. You'll find a few more commands in the = (System) menu, 
Windows menu. the menu marked with the = icon at the far left of the menu bar. 


Window hopping 


Each window that you open is numbered in the upper right 
corner. Usually, the Module window is window 1 and the 
Watches window is window 2. Whatever window you open after 
that will be window 3, and so on. 


This numbering system gives you a quick, easy means of moving 
from one window to another. You can make any of the first nine 
open windows the active window by pressing Alt in combination 
with the window number. If you press Alt-2, for example, to make 
the Watches window active, any commands you choose will affect 
that window and the items in it. 


F6 is the hot key forthe You can also cycle through the windows onscreen by choosing 

Window |Next Window. window | Next or pressing F6. This is handy if an open window's 
number is covered up so you don’t know which number to press 
to make it active. 


2 =f you have a mouse, you can also activate a window by clicking 
it. 


To see a list of all open windows, choose Window from the menu 
bar. The bottom half of the Window menu lists up to nine open 
windows from which you can make a selection. Just press the 
number of a window to make it the active one. 


If you have more than nine windows open, the window list will 
include a Window Pick command; choose it to open a pop-up 
menu of all the windows open onscreen. 


Tab and Shift-Tab are the hot If a window has panes—areas of the window reserved for a 
keys for Window! Next Pane. — specific type of data—you can move from one pane to another by 
choosing Window | Next Pane or pressing Tab or Shift-Tab. 


Chapter 2, Debugging and Turbo Debugger 33 


34 


You can also click the pane with the mouse. 


The most pane-ful window in Turbo Debugger is the CPU 
window, which has five panes. 


As you hop from pane to pane, you'll notice that a blinking cursor 
appears in some panes, and a highlight bar appears in others. If a 
cursor appears, you move around the text using standard keypad 
commands. (PgUp, Ctrl-Home, and Ctrl-PgUp, for example, move the 
cursor up one screen, to the top of pane, or to the top of the list, 
respectively.) You can also use WordStar-like hot keys for moving 
around in the pane. Refer to Chapter 13 for a table of keystroke 
commands in panes. 


If there's a highlight bar in a pane instead of a cursor, you can still 
use standard cursor-movement keys to get around, but a couple 
of special keystrokes also apply. In alphabetical lists, for example, 
you can select by typing. As you type each letter, the highlight bar 
moves to the first item starting with the letters you’ve just typed. 
The position of the cursor in the highlighted item indicates how 
much of the name you have already typed. Once the highlight bar 
is on the desired item, your search is complete. This incremental 
matching or select by typing minimizes the number of characters 
you must type in order to choose an item from a list. 


Once an item is selected (highlighted) from a list, you can press 
Alt-F10 or Ctrl-F10 to choose a command relevant to it from its local 
menu. In many lists, you can also just press Enter once you have 
selected an item. This acts as a hot key to one of the commonly 
used local menu commands. The exact function of the Enter key in 
these cases is described in the reference section starting on page 
197. 


Finally, a number of panes let you start typing a new value or 
search string without choosing a command first. This usually 
applies to the most frequently used local menu command in a 
pane or window—like Goto in a Module window, Search in a File 
window, or Change ina Registers window. 


Moving and resizing windows 


When you open a new window in Turbo Debugger, it appears 
near the current cursor location and has a default size suitable for 
the kind of window it is. If you find either the size or the location 
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of the window inconvenient, you can use the Window | Size/ 
Move command to adjust the size or location of the window. 


Cui-F5 is the hot key forthe When you move or resize a window, your active window border 
Window!Size/Move changes to a single-line border. You can then use the arrow keys 
command. ‘ ae 
to move the window around or Shift with the arrow keys to 
change the size of the window onscreen. Press Enter when you're 
satisfied. 


fee If you have a mouse, moving and resizing a window is even 
easier: 


m Drag the resize box in the lower right corner to change the size 
of the window. 


a Drag the title bar or any edge (but not the scroll bars) to move 
the window around. 


_ F5isthe hotkey forthe If you want to enlarge or reduce a window quickly, choose 
Window!Zoom command. window |Zoom, or click the mouse on the zoom box or the iconize 
box in the upper right corner. 


Finally, if you want to get a window out of the way temporarily 
but don’t want to close it, make the window active, then choose 
Window | Iconize/Restore. The window will shrink to a tiny box 
(icon) with only its name, close box, and zoom box visible. To 
restore the window to its original form, make it active and choose 
Window | Iconize/Restore again, or click your mouse on the zoom 
box. 


Closing and recovering windows 


Alt-F3 is the hot key for When you are through working in a window, you can close it by 
Window ! Close. choosing Window | Close, or pressing Alt-F3, the hot key for this 
command. 


na. =s«sf you have a mouse, you can also click the close box in the upper 
left corner of the window. 


Alt-F6 Is the hotkey for Jf you close a window by mistake, you can recover it by choosing 
Window! Undo Close. window | Undo Close or by pressing Alt-F6. This works only for the 
last window you closed. 


You can also restore your Turbo Debugger screen to the layout it 
had when you first entered the program. Just choose = (System) | 
Restore Standard. 
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Getting help 


Finally, if your program has overwritten your environment screen 
with output (because you turned off screen swapping), you can 
clean it up again with = (System) | Repaint Desktop. 


Saving your window layout 


Use the Options | Save Options command to save a specific 
window configuration once you have the screen arranged the way 
you like. In the Save Configuration dialog box, tab to Layout and 
press Spacebar to toggle it on. The screen will then appear with 
your chosen layout each time you start Turbo Debugger from 
DOS, if the configuration has been saved to a file called 
TDCONFIG.TD. This is the only configuration file that is loaded 
automatically when Turbo Debugger is loaded. Other 
configurations can be loaded by using the Options | Restore 
Options command, if they have been saved to configuration files 
with a different name. 


As you've seen, Turbo Debugger goes out of its way to make 
debugging easy for you. It doesn’t require you to remember 
obscure commands; it keeps lists of what you type, in case you 
want to repeat it; it lets you define macros; and it offers incredible 
control of windows. Even so, Turbo Debugger is a sophisticated 
program with lots of features and commands. To avoid potential 
confusion, Turbo Debugger offers the following help features: 


= An activity indicator in the upper right corner always displays 
the current activity. For example, if your cursor is ina window, 
the activity indicator reads READY; if there’s a menu visible, it 
reads MENU; if you’re in a dialog box, it reads PROMPT. If you ever 
get confused about what's happening in Turbo Debugger, look 
at the activity indicator for help. (Other activity indicator 
modes are SIZE/MOVE, MOVE, ERROR, RECORDING, WAIT, RUNNING, MENU, 
HELP, STATUS, and PLAYBACK.) 


u The active window is always topmost and has a double line 
around it. 

w You can access an extensive context-sensitive help system by 
pressing F1. Press F1 again to bring up an index of help topics 
from which you can select what you need. 

u The status line at the bottom of the screen always offers a quick 
reference summary of keystroke commands. The line changes 
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as you press Alt or Ctrl. Whenever you are in the menu system, 
the status line offers a one-line synopsis of the current menu 
command. 


For more information on the last two avenues for help, read the 
following two sections. 


Online help Turbo Debugger, like other Borland products, gives context- 
sensitive onscreen help at the touch of a single key. Help is 
available anytime you’re within a menu or window, as well as 
when an error message or prompt is displayed. 


Press Ff to bring up a Help screen showing information pertinent 
to the current context (window or menu). If you have a mouse, 
eg: Youccan also bring up help by clicking F1 in the status line. Some 

, Help screens contain highlighted keywords that let you get addi- 
tional help on that topic. Use Tab and Shift-Tab to move to any key- 
word and then press Enter to get to its screen. Use the Home and 
End keys to go to the first and last keywords on the screen, 
respectively. 


Index Shift-F] | | YOucan also access the onscreen help feature by choosing Help 


Previous topic Alt-Fl from the menu bar (Alt-H). 
Help on help 


If you want to return to a previous Help screen, press Alf-F1 or 
choose Previous from the Help menu. From within the Help 
system, use PgUp to scroll back through the last 20 help screens. 
(PgDn only works when you’re in a group of related screens.) To 
access the Help Index, press Shift-F1 (or F1 from within the Help 
system), or choose Index from the Help menu. To get help on 
Help, choose Help| Help on Help. To exit from Help, press Esc. 


You can get online help for Jf you are using Turbo Pascal or Turbo C, and you want help on 
Seal ee language-specific reserved words and functions such as you have 
' in the integrated debuggers for these languages, you can get it via 
a RAM-resident utility called THELP.COM that comes with Turbo 
Pascal and Turbo C. To use THELP.COM, 


1. Make sure that both THELP.COM and the help file for the 
language you are using (TURBO.HLP for Turbo Pascal, 
TCHELP.TCH for Turbo C) are copied into your Turbo 
Debugger directory or a directory on your path. 


2. Type THELP and press Enter. 
3. Go into Turbo Debugger. 
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The status line 


Figure 2.5 
The normal status line 


Figure 2.6 
The status line with Alt pressed 
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4. To open a Help screen on any reserved word or function, 
position the cursor under the word you want help on, then 
press 5 on the numeric keypad. (THELP won't work if you use 
the 5on your keyboard.) 


5. You can then use the help just as you would in the integrated 
debugger, paging through related screens, using Alf-F1 to 
return to previous screens, and pressing Enter to bring up a 
screen on a selected keyword. 


6. To exit the Help screen, press Esc. 


For more information on THELP, consult the THELP.DOC file for 
the Turbo language you are using. 


Wherever you’re in Turbo Debugger, a quick-reference help line 
appears at the bottom of the screen. This status line provides at- 
a-glance keystroke or menu command help for your current 
context. 


In a window 


The normal status line shows the commands performed by the 
function keys and looks like this: 


Bi-Help [z.-Bkpt [x/-Mod [f/-Here gi-Zoom i:-Next [#/-Trace |z:-Step [Run (3l.-Menu | 


If you hold down the Alt key for a second or two, the commands 
performed by the Alt keys are displayed. 


itmez--Bkpt at. [x-Close (f/-Back [#'-User Ui--Undo [zj-Instr |g:-Rtn |i-To [gl-Local| 


If you hold down the Ctrl key for a second or two, the commands 
performed by the Ctr letter keys are displayed. This status line 
changes depending on the current window and current pane, and 
it shows the single-keystroke equivalents for the current local 
menu. If there are more local menu commands than can be 
described on the status line, only the first keys are shown. You 
can view all the available commands on a local menu by pressing 
Alt-F10 or Ctrl-F10 to pop up the entire menu. 
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Figure 2.7 
The status line with Ctd 
pressed 
fea If you have a mouse, all you have to do to execute an Alt- or Cirl- 
key command is click the command in the status line. 


Ctrl: IEDR Teele rs en Ped ae 


In a menu or dialog box 


Whenever you are in a menu or a dialog box, the status line 
displays a one-line explanation of what the current item does. For 
example, if you have highlighted View | Registers, the status line 
says Open a CPU registers window. 


The status line gives you menu help whether you are in a global 
menu or a local menu. 
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A quick example 


If you are itching to use Turbo Debugger and aren’t the sort of 
person to work through the whole manual first, this chapter gives 
you enough knowledge to debug your first program. Once you’ve 
learned the basic concepts described here, the well-integrated, 
intuitive environment and context-sensitive help system let you 
learn as you go along. 


This chapter leads you through all Turbo Debugger’s basic fea- 
tures. After describing the demo programs—one in C and one in 
Pascal—provided on the distribution disks, it shows you how to 
g run and stop program execution 

m examine the contents of program variables 

g look at complex data objects, like arrays and structures 
change the value of variables 


The demo programs 


The demo programs (TCDEMO.C for C and TPDEMO.PAS for 
Pascal) introduce you to the two main things you need to know to 
debug a program: how to stop and start your program, and how 
to examine your programs variables and data structures. The 
programs themselves are not meant to be terribly useful: Some of 
their code and data structures exist solely to show you Turbo 
Debugger’s capabilities. 
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Getting In 


Figure 3.1 
The startup screen showing 
TCDEMO 


Getting out 


Each demo program lets you type in some lines of text or the 
name of a data file, then counts the number of words and letters 
that you entered or that it reads from the file. At the end of the 
program, each displays some statistics about the text, including 
the average number of words per line and the frequency of each 
letter. 


Make sure that your current directory contains the two files 
needed for each tutorial: TCDEMO.C and TCDEMO.EXE for the 
C example, TPDEMO.PAS and TPDEMO.EXE for the Pascal 
example. 


To start the C program, enter 
TD TCDEMO 

To start the Pascal program, enter 
TD TPDEMO 


Turbo Debugger loads the demo program, displays the startup 
screen, and positions the cursor at the start of the program. 


e: 
alate sold Teeter nares ange, Caer *argv[]); 


/* program entry point 
* 


> int main(int argc, char **argy) { 
unsigned int nlines, nwords, wordcount; 
unsigned long totalcharacters; 


nlines = 0; 

nwords = 0; 

totalcharacters = 0; 

showargs(arge, a v}; 

while treadaline( j= 0) { 
wordcount = makeintowords (buffer) ; 
nwords += wordcount; 
totalcharacters += analyzewords (buffer) ; 
nlines+; 


The startup screen consists of the menu bar, the Module and 
Watches windows, and the status line. 


To exit from the tutorial at any time and return to DOS, press Alt-X. 
If you get hopelessly lost following the tutorial, press Ctrl-F2 to 
reload the program and start at the beginning. However, Ctrl-F2 
doesn’t clear breakpoints or watches; you'll have to use Alt-F O to 
do that. (Alt-B D deletes all breakpoints too, of course, but some- 
times it’s faster to reload with Alt-F 0.) 
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Getting help 


Press Ff whenever you need help about the current window, 
menu command, dialog box, or error message. You can learn a lot 
by working your way through the menu system and pressing F/ 
at each command to get a summary of what it does. 


Using Turbo Debugger 


The menus 


Figure 3,2 
The menu bar 


F10 


m2 
[Esc] 
Tne status line 


Figure 3.3 
Tne status line 
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The top line of the screen shows the menu bar. To pull down a 
menu from it, press F10, use < or > to highlight your selection, 
and press Enter, or else press Alt in combination with the first letter 
of one of the menu names. 


ies iew<:cunks reakpoints/satas; 


Press F10 now. Notice that the cursor disappears from the Module 
window, and the File command on the menu bar becomes high- 
lighted. The bottom line of the screen also changes to indicate 
what sort of commands the File menu contains. 


Use the arrow keys to move around the menu system. Press J to 
pull down the menu for the highlighted item on the menu bar. 


You can also open a menu by clicking an item in the menu bar 
with your mouse. 


Press Esc to move back through the levels of the menu system. 
When just one menu item on the menu bar is highlighted, pres- 
sing Esc returns you to the Module window, with the menu bar no 
longer active. 


The status line at the bottom of the screen shows relevant function 
keys and what they do. 


FAERIE F SCT FSI FSS SEP OR F 7 Se Coo RSF SSO F 1 OST 


This line changes depending on what you are entering (menu 
commands, data in a dialog box, and so on). Hold Altdown for a 
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second or two, for example. Notice that the status line changes to 
show you the function keys you can use with Alt. 


Now press Ctrl for a second. The commands shown on the status 
line are the hot keys to the local menu commands for the current 
pane (area of the window). They change depending on which sort 
of window and which pane you are in. More about these later. 


As soon as you enter the menu system, the status line changes 
again to show you what the currently highlighted menu option 
does. Press F10 to go to the menu bar, and press — to highlight the 
File option. The status line now reads, “File oriented functions.” 
Use J to scroll through the options on the File menu, and watch 

fe. = the message change. Press Esc or click the Module window with 
your mouse to leave the menu system. 


The windows 


The window area takes up most of the screen. This is where you 
examine various parts of your program through the different 
windows. 


The display starts up with two windows: a Module window and 
the Watches window. Until you open more windows or adjust 
these two, they remain tiled. This means they fill the entire screen 
without overlapping. New windows automatically overlap 
existing windows until you move them. 

Figure 3.4 


The Module and Watches bd di i D ‘ice F 


windows, tiled program DoNuthin; 
> begin 
end. 


This is the Module window 
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Notice that the Module window has a double-line border and a 
highlighted title. This means it is the active window. You use the 
cursor keys (the arrow keys, Home, End, PgUp, and so on) to move 

around inside the active window. Now press F6to switch to 
another window. The Watches window becomes active, with a 
double-line border and a highlighted title. 


You use commands from the View menu to create new windows. 
For example, choose View | Stack to open a Stack window. The 
Stack window pops up on top of the Module window. 


Alt Now press Alt-F3 to remove the active window. The Stack window 
disappears. 


Turbo Debugger stores the last-closed window So you can recover 

it if you need to. If you accidentally close a window, choose 

Window | Undo Close. The Stack window reappears. You can also 
Alt press Alt-F6 to recover the last-closed window. 


The Window menu contains the commands that let you adjust the 
appearance of the windows you already have onscreen. You can 
both move the window around the screen and change its size. 
(You can use Cirl-F5 to do this too.) 


Choose Window | Size/Move and use the arrow keys to reposition 
the active window (the Stack window) on the screen. Next, hold 
Shift down and use the arrow keys to adjust the size of the 
window. Press Enter when you have defined a new size and 
position that you like. 


Now, to prepare for the next section, remove the Stack window by 
pressing Alt-F3. Depending on whether you've loaded the C or 
Pascal demo program, you should either continue with the next 
section (for the C sample) or move to the Pascal section on page 
52. 


Using the C demo program 


The filled arrow (>) in the left column of the Module window 
shows where Turbo Debugger stopped your program. Since you 
haven’t run your program yet, the arrow is on the first line of the 

program. Press F7 to trace a single source line. The arrow and 
cursor are now on the next executable line. 
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Figure 3.5 


Program stops on return from 
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function showargs 


Look at the right margin of the Module window title. It shows the 
line that the cursor is on. Move the cursor up and down with the 
arrow keys and notice how the line number in the title changes. 


As you can see from the Run menu, there are a number of ways to 
control the execution of your program. Let’s say you want to 
execute the program until it reaches line 39. 


First, position the cursor on line 39, then press F4. This runs the 
program up to (but not including) line 39. Now press F7, which 
executes one line of source code at a time; in this case, it executes 
line 39, a call to the function showargs. The cursor immediately 
jumps to line 151, where the definition of showargs is found. 
Continuing to press F7 would step you through the function 
showargs and then return you to the line following the call—line 
40. Instead, press Alt-F8 to make the program stop when showargs 
returns. This too returns you to line 40. This command is very 
useful when you want to jump past the end ofa function. 


If you had pressed F8 instead of F7on line 39, the cursor would 
have gone directly to line 40 instead of into the function. F8 is 
similar to F7in that it executes functions, but it doesn’t step 
through their source code. 


totalcharacters = 0; 

showargs(argc, argv); 

while (readaline() != 0) { 
wordcount = makeintowords (buffer); 
nwords += wordcount; 
totalcharacters += analyzewords (buffer); 
nlines+; 


printstatistics(nlines, nwords, totalcharacters); 
return(0); 


} 


/* make the buffer into a list of null-terminated words that end in 
* in two nulls, squish out white space 


* 
static int makeintowords(char «bufp) { 
; d int rd 


To execute the program until a specific place is reached, you can 
directly name the function or line number, without moving the 
cursor to that line in a source file and then running to that point. 
Press Alt-F9 to specify a label to run to. A dialog box appears. Type 
readaline and press Enter. The program runs, then stops at the 
beginning of function readaline (line 142). 
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setting 


breakpoints Another way to control where your program stops running is to 
set breakpoints. The simplest way to set a breakpoint is with the 
F2 key. Move the cursor to line 44 and press F2. Turbo Debugger 

highlights the line, indicating there is a breakpoint set on it. 


fx2 4 You can also use the mouse to toggle breakpoints by clicking the 
first two columns of the Module window. 


Figure 3.6 
A breakpoint at line 44 


totalcharacters = 0; 

Showargs(argc, argv); 

while (readaline(} I= 0) { 
wordcount = makeintowords (buffer); 
nwords += wordcount; 
totalcharacters += analyzewords (buffer); 
nlines++; 


printstatistics(nlines, nwords, totalcharacters); 
return(0); 


} 


/* make the buffer into a list of null-terminated words that end in 
* in two nulls, squish out white space 


" 
static int makeintowords(char *bufp) { 
; unsigned int nwords; 


Now press F9 to execute your program without interruption. The 
screen switches to the program's display. The demo program is 
now running and waiting for you to enter a line of text. Type abc, 
a space, def, and then press Enter. The display returns to the Turbo 
Debugger screen with the arrow on line 44, where you set a break- 
point that has stopped the program. Now press F2 again to toggle 
it off. 


See Chapter 7 for a complete description of breakpoints, including 
conditional and global breakpoints. 
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Using watches 


The Watches window at the bottom of the screen shows the value 
of variables you specify. For example, to watch the value of the 
variable nwords, move the cursor to the variable name on line 42 
and choose Watch from the Module window local menu (bring it 
up with Alt-F10 or choose the shortcut, Ctrl-W, from the status line). 


fn Click Ciri-Win the status line with your mouse. 


Figure 3.1 
AC variable in the Watches 
window 


Alt || F10 


totalcharacters = 0; 
showargs(argc, argv); 
while (readaline() != 0) { 
wordcount = makeintowords (buffer); 


nwords += wordcount; 
totalcharacters += analyzewords (buffer); 
niines++; 


prinespac sc leeinlanesi nwords, totalcharacters); 
return(0); 


} 


/* make the buffer into a list of null-terminated words that end in 
* in two nulls, squish out white space 


static int epaseeleatherd Seay «bufp) { 
snanensnsns We nword a de tas 


unsigned int 0 


nwords now appears in the Watches window at the bottom of the 
screen, along with its type (unsigned Int) and value. As you 
execute the program, Turbo Debugger updates this value to 
reflect the variable’s current value. 


Examining simple 
C data objects Once you have stopped your program, there are a number of 
ways Of looking at data using the Inspect command. This very 
powerful facility lets you examine data structures in the same 
way that you visualize them when you write a program. 


The Inspect commands (in various local menus and in the Data 
menu) let you examine any variable you specify. Suppose you 
want to look at the value of the variable nlines. Move the cursor so 
it is under one of the letters in nlines and choose Inspect from the 
Module window local menu (press Ciri-). An Inspector window 


pops up. 
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Figure 3.8 
An Inspector window 
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totalcharacters “ af 
showargs{arge, a 
while reataline( woe ) { 
WO vet = makeintowords (buffer); 
nwords += wordcount; 
totalcharacters += analyzewords (buffer); 
nlinest+; 
} [1]=inspecting alines=3=[t] [4] 
Gale @793E:FFCO 
return(0); unsi 


/* make the buffer into a list of null-terminated words that end in 
* in two nulls, squish out white space 


® 
static int makeintowords(char *bufp) { 
unsigned int nwords; 


The title tells you the variable name; the next line shows you its 
address in memory. The third line shows you what type of data is 
stored in nlines (it’s a C unsigned int). To the right is the current 
value of the variable. 


Now, having examined the variable, press Esc to close the 
Inspector window. You can also use Alt-F3 to remove the Inspector 
window, just like any other window, or you can click the close box 
with your mouse. 


Let's review what you actually did here. By pressing Ctrl, you took 
a shortcut to the local menu commands in the Module window. 
Pressing I specified the Inspect command. 


To examine a data item that is not conveniently displayed in the 
Module window, choose Data | Inspect. A dialog box appears, 
asking you to enter the variable to inspect. Type letterinfo and 
press Enter. An Inspector window appears, showing the values of 
the letterinfo array elements. The title of the Inspector window 
shows the name of the data you are inspecting. The first line 
under the title is the address in main memory of the first element 
of the array letterinfo. Use the arrow keys to scroll through the 26 
elements that make up the letterinfo array. The next section shows 
you how to examine this compound data object. 
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Examining 
compound C 
data objects 


Figure 3.9 
Inspecting a structure 


Alt 


Changing C data 
values 
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A compound data object, such as an array or structure, contains 
multiple components. Move to the fourth element of the letterinfo 
array (the one indicated by [3]). Press Alt-F10 to bring up the local 
menu for the Inspector window, then press / to choose Inspect. A 
new Inspector window appears, showing the contents of that 
element in the array. This Inspector window shows the contents 
of a structure of type linfo. 


totalcharacters = 0; —-Inspecting letterinfo-3 
showargs(argce, a v5 @793E:0852 
while (readaline() l= OD 

wordcount = make 

nwords += wordco 

totalcharacters 

nlines+; 


cbt haa 


struct linfo 


=Inspecting letterinfo{3|=4= 
/« make the buffer into a list of 9@793E:085E 


return(0); 


2 
static int makeintowords(char «buf 
unsigned int nwords; 


When you place the cursor over one of the member names, the 
data type of that member appears in the bottom pane of the 
Inspector window. If one of these members were in turn a 
compound data object, you could issue an Inspect command and 
dig down further into the data structure. 


Press Alt-F3 to remove both Inspector windows and return to the 
Module window. (Alt-F3 is a convenient way of removing several 
Inspector windows at once. If you had pressed Esc, only the latest 
Inspector window would have been deleted.) 


So far, you've learned how to look at data in the program. Now, 
let's change the value of data items. 


Use the arrow keys to go to line 38 in the source file. Place the 
cursor at the variable totalcharacters and press Cirl-I to inspect its 
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value. With the Inspector window open, press Alt-F10 to bring up 
the Inspector’s local menu, and choose the Change option. (You 
could also have done this directly by pressing Ctrl-C.) A dialog box 
appears, asking for the new value. 


Figure 3.10 er eakpoi nts who totionste. indowsy .e | pwr 


The Change dialog box demo 
static pry she castine arge, rere “earav[})3 


/* program entry point 


78BE : FFC6 


unsigned i 
unsigned* Jon 


unsigned 1 


* 
int main(int = a totalcharacters=3=[1] [+] 


nlines 
nwords || ag RaRSE Peer e Wr NR UDMA AY aA OU ie bat 


totalch z total c erat ers + cy 
1ST oe at r pepeat : 


showarg peat 


totalcharacters += analyzewords (buffer); 
nlines++; 


At this point, you can enter any C expression that evaluates toa 
number. Type totalcharacters + 4 and press Enter. The value in the 
Inspector window now shows the new value, 10L (0xA). 


To change a data item that isn’t displayed in the Module window, 
choose Data | Evaluate/ Modify. A dialog box appears. Enter the 
name of the variable to change in the first input box: Type argc 
and press Enter. Then press Tab twice to move to the input box 
labeled New Value. Type 123 and press Enter. The result (second 
box) changes to int 123 (0x7B). 
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Figure 3.11 

The Evaluate/Modify dialog Se tedeng 6 ae 
box (int argc, char *argv[]); 

— Evaluate/nodif 


That's a quick introduction to using the Turbo Debugger with a 
Turbo C program. Chapter 14 offers a more extensive debugging 
sample. 


Using the Pascal sample program 


The filled arrow (>) in the left column of the Module window 
shows where Turbo Debugger stopped your program. Since you 
haven't run your program yet, the arrow is on the first line of the 

program. Press F7 to trace a single source line. The arrow and 
cursor are now on the next executable line. 


Look at the right margin of the Module window title. It shows the 
line that the cursor is on. Move the cursor up and down with the 
arrow keys and notice how the line number in the title changes. 


To make the program execute until it reaches line 221, move the 
cursor to that line and then press F4. TPDEMO prompts you to 
enter a string. Type ABC, a space, DEF, and then press Enter. Now, 
with the cursor still on line 221, press F7 twice to execute two 
more lines of source code. Since the second line you executed is a 
call to a different procedure, the arrow now appears on the first 
line of the function ProcessLine. Continuing to press F7 would step 
you through the function ProcessLine and then return you to the 
line following the call—line 224. Instead, press Alt-F8 to make the 

program stop when ProcessLine returns. This command is very 
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Figure 3.12 
The program stops after 
returning from a procedure 


Alt 


setting 
breakpoints 


@a 
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useful when you want to jump past the end of a function or 
procedure. 


If you had pressed F8 instead of F7on line 221, the cursor would 
have gone directly to line 224 instead of into the function. F8 is 
similar to F7in that it executes functions, but it doesn’t step 
through their source code. 


mreakpoints nat: RO SARL Os et Ll Teeaaneen ata READY 
+ e A 


=Modu PDEMO Fi - 
while Buffer 2 '' do 
begin 

ProcessLine(Buffer); 

Buffer := GetLine; 


end; 
ShowResults; 
ParmsOnHeap; 


To execute the program until a specific place is reached, you can 
directly name the function or line number, without moving the 
cursor to that line in a source file and then running to that point. 
Press Alt-F9 to specify a label to run to. A dialog box appears. Type 
GetLine and press Enter. The program runs, then stops at the 
beginning of function GetLine. 


Another way to control where your program stops running is to 
set breakpoints. The simplest way to set a breakpoint is with the 
F2 key. Move the cursor to line 121 and press F2. Turbo Debugger 
highlights the line, indicating there is a breakpoint set on it. 


You can also use the mouse to toggle breakpoints by clicking the 
first two columns of the Module window. 
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Figure 3.13 
Abreakpoint at line 12] 


Using watches 


foe. 


Wile jyiew Kun [reakpoints Jata ‘options 
aj=Module: TPDEMO File: TPDEMO.PA 

i: Integer; 

WordLen : Word; 


begin { ProcessLine } 
> Inc(N umLines) ; 


i: 1; 
while j < Length($) do 


a Le Skip non-letters } 
waite (t <= pate and not IsLetter(S[i]) do 


Inc(i); 


{ cts end a word, bump letter & word counters } 
lo 
mile Gi <= OF easth($)) and IsLetter(S[i]) do 
egin 
Inc(NumLetters) ; 
bel 


Now press F9 to execute your program without interruption. The 
screen switches to the program's display. The demo program is 
now running and waiting for you to enter a line of text. Type abc, 
a space, def, and then press Enter. The display returns to the Turbo 
Debugger screen with the arrow on line 121, where you set a 
breakpoint that has stopped the program. Now press F2 again to 
toggle it off. 


See Chapter 7 for a complete description of breakpoints, including 
conditional and global breakpoints. 


The Watches window at the bottom of the screen shows the value 
of variables you specify. For example, to watch the value of the 
variable Num Words, move the cursor to the variable name on line 
144 and choose Watch from the Module window local menu 
(bring it up with Alt-F10, or choose the shortcut, Cirl-W, from the 
status line). 


You can also click Cirl-Win the status line with your mouse. 
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Figure 3.1] 
A Pascal variable in the 
Watches window 
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| .& file jiew [un. Ereakpoints ‘sata: Sas i 
(sJ=Module: TPDEMO File: TPDEMO.PAS 1 

Inc(LetterTable[UpCase(S[i])]. count); 
if WordLen = 0 then bump counter } 
: Ine(Lettertable Upcase(SI{I)1. .FirstLetter); 
ne 
Inc(WordLen); 

end; 


{ Bump word count info } 
if WordLen > 0 then 
begin 
Inc(NumWords) ; 
if Wordlen <= MaxWordLen then 
Inc(WordLenTable [WordLen]); 


end; 
end; { while } 
end; { ProcessLine } 


function GetLine : 
Lg? 


NumWords now appears in the Watches window at the bottom of 
the screen, along with its type (Word) and value. As you execute 
the program, Turbo Debugger updates this value to reflect the 
variable’s current value. 


Once you have stopped your program, there are a number of 
ways Of looking at data using the Inspect command. This very 
powerful facility lets you examine data structures in the same 
way that you visualize them when you write a program. 


The Inspect commands (in various local menus and in the Data 
menu) let you examine any variable you specify. Suppose you 
want to look at the value of the variable NumLines. Move the 
cursor back to line 121 so it’s under one of the letters in NumLines 
and press Ctrl-I. An Inspector window pops up. 
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Figure 3.15 
An Inspector window 


FARR ST TT EADY 
dules TPDEMO File: TPDEMO.PAS 121———_—_ ————_—_—_—__ 

i: Integer; 

WordLen : 


begin { ProcessLine } 
Inc(NumLines) ; 

{3:2 1; eelalaspect {ng NunLines=3=[1] [tJ] => 

while j ya 


77D1:00. 
ORD 


in 

Skip SNe pte 
while” {i <« rit 
Inc(i); 


and not foes THI) do 


1 One es end aH word, bump letter & word counters } 
L 
while a <« Length(S)) and IsLetter(S[i]) do 


begin 
tne NumLetters) ; 
Inc LetterTable(upCase(S[i])]. Count); 


The first line tells you the variable name; the second line shows its 
address in memory. The third line tells you what type of data is 
stored in NumLines (it’s a Pascal Word) and displays the current 
value of the variable. 


Now, having examined the variable, press Esc to close the 
Inspector window. You can also use Alt-F3 to remove the Inspector 
window, just like any other window, or you can click the close box 
with your mouse. 


Let’s review what you actually did here. By pressing Cir, you used 
a hot key for the local menu commands in the Module window. 
Pressing I specified the Inspect command. 


To examine a data item that is not conveniently displayed in the 
Module window, choose Data | Inspect. A dialog box appears, 
asking you to enter the variable to inspect. Type LetterTable and 
press Enter. An Inspector window appears, showing the value of 
LetterTable. Use the arrow keys to scroll through the 26 elements 
that make up LetterTable. The title of the Inspector window shows 
the name and type of the data you are inspecting, exactly as the 
declaration for this data appears in the source file. The next 
section shows you how to examine this compound data object. 
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Figure 3.16 
Inspecting a record 


Changing Pascal 
data values 
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A compound data object, such as an array or structure, contains 
multiple components. Move to the fourth element of the 
LetterTable array (the one indicated by [’D’}). Press Alt-F10 to bring 
up the local menu for the Inspector window, then choose Inspect. 
A new Inspector window appears, showing the contents of that 
element in the array. This Inspector window shows the contents 
of a record of type LInfoRec. 


Worden: Word; 


begin { ProcessLine } 
eee ees 
i 

while i <= Length(S) do 

begi (u]=Inspecting Lettertable|'D 
('s Skip non-letter}/@77D1: GO66 
while {i <= Lengt sist x 


= 0; 
wile a <= Length(s)) and IsLetter(S[i]) do 


ine NumLetters) ; 
Inc LetterTablefUpCase(S[il)1. Count) ; 


When you place the cursor over one of the member names, the 
data type of that member appears in the bottom pane of the 
Inspector window. If one of these members were in turn a 
compound data object, you could issue an Inspect command and 
dig down further into the data structure. 


Press Alt-F3 to remove both Inspector windows and return to the 
Module window. (Alt-F3 is a convenient way of removing several 
Inspector windows at once. If you had pressed Esc, only the 
topmost Inspector window would have been deleted.) 


So far, you've learned how to look at data in the program. Now, 
let's change the value of data items. 


Use the arrow keys to go to line 103 in the source file. Place the 
cursor at the variable called NumLetters and press Ctrl-I to inspect 
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Figure 3.17 
The Change dialog box 


its value. With the Inspector window open, press Alt-F10 to bring 
up the Inspector window’s local menu. Choose the Change option. 
(You could also have done this directly by pressing Ctrl-C.) A 
dialog box appears, asking for the new value. 


procedure Init; 
in 


NumLines := 0; NumWords := 0; NumLetters := 0; 
FillChar LetterTable, a hunLetters-3[1] [4 


FillChar(WordLenTable, Size0f (Wo 
rele Enter a string to proce] (Iie 


end; { Init } aus 

[s]=Enter n 
}NumLetters +4 00 
OK sm Cancel gam Help wf 


procedure ProcessLine(va 
Fench hen IsLetter(ch ; 

IsLetter := UpCase(ch) 
end; { IsLetter } 


var 
i: Integer; 


At this point, you can enter any Pascal expression that evaluates 
to a number. Type NumLetters + 4 and press Enter. The value in the 
Inspector window now shows the new value, 10. 


To change a data item that isn’t displayed in the Module window, 
choose Data | Evaluate/ Modify. A dialog box appears. Enter the 
name of the variable to change. Type NumLines and press Enter. The 
result is displayed in the middle pane. Press Tab twice, then type 
123 and press Enter. This sets the variable NumLines to 123. 
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Figure 3.18 
The Evaluate/Modify dialog 
box 
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AT eshte toe ah ieee LRM aS ce gP ROMPT 
ule: TPDEMO File: TPDEHO.PAS 103———————_———_—___—__—_1 


procedure Init; 

begin ) 
NumLines :jif 
FillChar(Lif 
Fill Char (Wik 
Writeln('E 

end; { Init 


var 
i: Integer; 


That wraps up our quick introduction to using Turbo Debugger 
with a Turbo Pascal program. Chapter 14 offers a more extensive 
debugging sample. 
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Starting Turbo Debugger 


This chapter tells you how to prepare programs for debugging. 
We show you how to start Turbo Debugger from the DOS com- 
mand line, and how to tailor its many command-line options to 
suit the program you are debugging. We explain how to make 
these options permanent in a configuration file. You also learn 
how to run a DOS command processor from within a Turbo 
Debugger session and, finally, how to return to DOS when you 
are done. 


Preparing programs for debugging 


When you compile and link with one of Borland’s Turbo 
languages, you can tell the compiler to generate full debugging 
information. If you have compiled your program’s object modules 
without any debugging information, you must recompile all its 
modules to have full source debugging capabilities throughout 
your program. It is possible to generate debug information only 
for specific modules (you might have to do this if you’re 
debugging a large program), but you will find it annoying later to 
enter a module that doesn’t have any debug information 
available. We suggest recompiling all modules. 
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Preparing Turbo C 
programs 


Preparing Turbo 
Pascal programs 


Just like this, with no spaces 
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If you’re using the Turbo C++ integrated environment (TC), open 
the Debugger dialog box (choose Options | Debugger) and set the 
Source Debugging radio button to Standalone before you compile 
your source modules. For Turbo C 2.0, set Debug | Source 
Debugging to Standalone. 


If you’re using the command-line compiler (TCC), specify the -v 
command-line option. 


If you’re using TLINK as a standalone linker, you must use the /v 
option to append debugging information at the end of the .EXE 
file. 


You also should make sure optimizing is disabled. Either don’t 
use the —O option or specify -O-— to turn off the -O in your 
TURBOC.CFG file. This eliminates the few occasions when Turbo 
Debugger appears to skip over lines of source code when you’re 
stepping through a program. 


First, make sure that you have version 5.0 or later of Turbo Pascal. 
Earlier versions do not have the ability to bundle debugging 
information into the .EXE file so that Turbo Debugger can use it. 


If you’re using the integrated environment (TURBO.EXE), go to 
the Debug menu and change the Standalone Debugging setting to 
On. Turn Options | Compiler | Debug Information On or use the 
{$D+} compiler directive. If you want to be able to reference local 
symbols (any declared within procedures and functions), you 
must either set Options | Compiler | Local Symbols to On or put 
this directive at the start of your program: 


{$L+] 
You can then compile your program. 


If you’re using the command-line version (TPC.EXE), you must 
compile using the /v command-line option. Debug information 
and local symbols are, by default, generated. If you don’t want 

them, you can use /$ command-line options to disable them. 
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Preparing Turbo 
Assembler 
programs 


Preparing 
Microsoft 
programs 


To debug a Turbo Assembler program, specify the -zi command- 
line option to get full debugging information. 


To link your program with TLINK, use the /v option to append 
debugging information at the end of the .EXE file. 


See the documentation on your distribution disks for information 
about how to use the utility program TDCONVRT.EXE, which 
converts CodeView executable programs to Turbo Debugger 
format. 


Running Turbo Debugger 


To debug a program with Turbo Debugger, simply type TD at the 
DOS prompt, followed by an optional set of command-line 
arguments and the name of the program, and press Enter. Turbo 
Debugger then loads your program, displaying its source code so 
you can step through your program statement by statement. 


The generic command-line format is 
TD [options] [progname [progargs}] 


The items enclosed in brackets are optional; if you include any, 
type them without the brackets. Progname is the name of the pro- 
gram to debug. You can follow a program name with arguments. 
Here are some example command lines: 


Command Action 


td -sc progl ab _ Starts the debugger with —sce option and loads 
program prog] with two command-line 
arguments, a and b. 


td prog2 -x Starts the debugger with default options and 
loads program prog2 with one argument, —x. 


If you simply type 1D Enter, Turbo Debugger loads and uses its 
default options. 
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When you run a program in Turbo Debugger, you need to have 
both its .EXE file and the original source files available. Turbo 
Debugger searches for source files first in the directory the 
compiler found them in when it compiled, second in the directory 
specified in the Options | Path for Source command, third in the 
current directory, and fourth in the directory the .EXE file is in. 


You must have already compiled your source code into an 
executable (.EXE) file with full debugging information turned on 
before debugging with Turbo Debugger. 


Remember, Turbo Debugger works only with programs in Turbo 
Pascal 5.0 or later, Turbo C 2.0 or later, or Turbo Assembler 1.0 or 
later. 


If you’re running your program from the DOS prompt and notice 
a bug, you have to exit from your program and load it under the 
debugger before you can begin debugging. 


Command-line options 


Appendix A has an easy-to- 


use list of Turbo Debuggers 
command-line options. 


Loading the 


configuration file 
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(-c) 


All Turbo Debugger command-line options start with a hyphen (-) 
and are separated from the TD command and each other by at 
least one space. You can explicitly turn a command-line option off 
by following the option with another hyphen. For example, —vg— 
turns off a complete graphics save. You can do this if an option 
has been permanently enabled in the configuration file. You can 
modify the configuration file by using the TDINST configuration 
program described in Appendix D. 


The following sections describe all available command-line 
options. 


This option loads the specified configuration file. There must not 
be a space between -¢ and the file name. 


If the —c option isn’t included, TDCONFIG.TD is loaded if it 
exists. Here’s an example: 


TD ~cMYCONF.TD TCDEMO 


This loads the configuration file MYCONF.TD and the source 
code for TCDEMO. 
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Display updating 


(-d) All-d options affect the way in which display updating is 
performed. 


-do Runs Turbo Debugger on your secondary display. View 
your program's screen on the primary display, and run 
the debugger on the secondary one. 


-dp The default option for color displays. Shows the debugger 
on one display page and the program being debugged on 
another, minimizing the time it takes to swap between the 
two screens. You can use this option only ona display 
that has multiple display pages. You can’t use this option 
if the program you are debugging uses multiple display 
pages itself. This is the default for display updating. 


-ds The default option for monochrome displays. Maintains a 
separate screen image for the debugger and the program 
being debugged by loading the entire screen from 
memory each time your program is run or the debugger 
is restarted. This is the most time-consuming method of 
displaying the two screen images, but works on any 
display hardware and with programs that do unusual 
things to the display. 


Getting help (-h 


and —?) These options display a screenful of help that describes Turbo 
Debugger’s command-line syntax and options. 


Process ID 


switching (-i) This option enables process ID switching. Don’t use this option 
when you are debugging inside DOS or when DOS system calls 
are active. See Appendix B for more technical information on this 
feature. You needn’t be concerned with this option to debug most 
programs. 


Keystroke 


recording (-k) This option enables keystroke recording in the Keystroke 
Recording pane of the Execution History window. 
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Assembler-mode 


startup (-l) 


Setting heap size 
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(-m) 


= 


Mouse support 
(-P) 


If you use this option, all keystrokes that you type during a 
debugging session will be recorded to a disk file. Then you can 
recover to a previous point in your debugging session by having 
Turbo Debugger reload your program and play back the recorded 
keystrokes. Turbo Debugger records both the keys you press 
while you’re in Turbo Debugger and the keys you press while 
your program is running. 


This option forces startup in assembler mode, showing the CPU 
window. Turbo Debugger does not execute your program's 
startup code, which usually executes automatically when you 
load your program into the debugger. This means that you can 
step through your startup code. 


This option sets the working heap used by Turbo Debugger to 
NK, where the syntax is 


-mN 


and N is the number of kilobytes. A space must not exist between 
the —m option and the size of the heap. Here’s an example: 


TD -m10 TCDEMO.EXE 


The default heap size is 18K; the low boundary is 7K. If you need 
memory, use this option to reduce the amount of heap Turbo 
Debugger uses. Turbo Debugger stores transient information, 
such as command history lists and breakpoints, in the heap. 


If you specify a heap size of 0 (zero) with the -m command-line 
option (-m0), Turbo Debugger uses the maximum that it’s able to 
use, usually 18K. 


This option enables mouse support. However, since the default 
for mouse support in Turbo Debugger is On, you won’t have 
much use for the -p option unless you use TDINST to change the 
default to Off. If you want to disable the mouse, use —p-. 
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Remote 


debugging (-f)  All-r options affect the remote debugging link. 


-r 


-rpN 


-rsN 


Source code 


Enables debugging on a remote system over the serial 
link. Uses the default serial port (COM1) and speed (115 
Kbaud), unless you have changed them with TDINST. 


Sets the remote link port to port N. N can be 1 or 2 to 
indicate COM1 or COM2, respectively. 


Sets the remote link speed. N can be 1 for 9600 baud, 2 for 
40 Kbaud, or 3 for 115 Kbaud. 


handling (-S) All-s options affect the way Turbo Debugger handles source 
code and program identifiers. 


This option does not affect —se 
Pascal, because it is not 
case-sensitive. 


-smN 
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Ignores case when you enter symbol names, even if your 
program has been linked with case sensitivity enabled. 


Without the -se option, Turbo Debugger ignores case 
only if you've linked your program with the case ignore 
option enabled. 


Sets one or more source directories to scan for source files; 
the syntax is 


~sddirname 


To set multiple directories, use the -sd option 
repeatedly—only one directory name can be specified 
with each —sd option. Directories are searched in the 
order specified. dirname can be a relative or absolute path 
and can include a disk letter. If the configuration file 
specifies any directories, the ones specified by the —sd 
option are added to the end of that list. 


This option sets the symbol table reserved memory size. 
Follow it with the number of kilobytes you want to 
reserve, like this: 


-smN 


where N is the number of kilobytes. Use this option if you 
want to load a symbol table manually with the 
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Video hardware 
(-v) 


Overlay pool size 
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(-y) 


Use TDINST to set a 
permanent overlay code 
pool size. 


File | Symbol Load command. You may have to 
experiment with the amount of memory to reserve. 


All -v options affect how Turbo Debugger handles the video 
hardware. 


-vg 


Saves complete graphics image on program screen. 
Requires an extra 8K of memory, but can debug programs 
that use certain graphics display modes. Try this option if 
your program's graphics screen becomes corrupted when 
running under Turbo Debugger. 

43 /50-line display is not allowed. Specifying this option 
saves some memory. Use this if you’re running on an 
EGA or VGA and know you won't switch into 43- or 50- 
line mode once Turbo Debugger is running. 


Enables the EGA palette save. 


The -y options are used to set the size of the overlay pool size, 
either in main memory or in EMS memory. 


-yN 


-~yeN 


This option sets the overlay pool size in main memory. 
The syntax is as follows, where N is the number of 
kilobytes you want to reserve: 


-yN 


Normally, Turbo Debugger uses a 80K code pool size. The 
smallest pool size that you can set is 20K, and the largest 
is 200K. 


Use this option if you do not have enough memory to 
load your program under Turbo Debugger, or if you are 
debugging small programs and want to improve Turbo 
Debugger’s performance. The smaller the code pool size, 
the more often Turbo Debugger loads program overlays 
from disk, and the slower it responds. With a larger code 
pool, there is less memory available for the program you 
are debugging, but Turbo Debugger runs faster. 


This option sets the overlay pool size in EMS memory. 
Use this option if you need to free up some EMS memory 
for the program you are debugging. The syntax is as 
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follows, where N is the number of 16K EMS pages you 
want to reserve: 


-yeN 


For example, —ye4 sets the overlay pool to four pages. The 
default is twelve 16K EMS pages. 


Use -ye0 to disable the EMS overlay pool. 


Configuration files 


Turbo Debugger uses a configuration file to override built-in 
default values for command-line options. You can use TDINST to 
set the options that Turbo Debugger will default to if there is no 
configuration file. You can also use it to build configuration files. 


Turbo Debugger looks for the configuration file TDCONFIG.TD 
first in the current directory, next in the TURBO directory set up 
with the TDINST installation program, and then in the directory 
that contains TD.EXE. If you are running on DOS 2.x, Turbo De- 
bugger won’t look for TDCONFIG.TD in the TD.EXE directory. 


Appendix D describeshow If Turbo Debugger finds a configuration file, the settings in that 
fo use the installation pro- file override its built-in defaults. Any command-line options that 
gram to create configuration : 
files, you supply when you start Turbo Debugger from DOS override 


those default options and any values in TDCONFIG.TD. 


The Options menu 


Language... Source | he Options menu lets you set or adjust a number of parameters 
Macros > | that control the overall appearance and operation of Turbo 

ri agra see Debugger. The following sections describe each menu command 
Save options... and refer you to other sections of the manual where you can find 


Restore options... ° 
P more details. 


The Language 


command Chapter 9 describes how to set the current expression language 
and how it affects the way you enter expressions. 
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Tne Macros menu 


Create Alt= 
Stop recording Alt- 


emove 
Delete al] 


Create 


Stop Recording 


Remove 


Delete All 


Display Options 
command 
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The Macros command displays another menu that lets you define 
new keystroke macros or delete ones that you have already 
assigned to a key. It has the following commands: Create, Stop 
Recording, Remove, and Delete All. 


Starts recording keystrokes that you are assigning to a key (for 
example, Alt-M). To begin a recording session, choose Options | 
Macros | Create. You are prompted for the key you want to assign 
the macro to. The message RECORDING is displayed in the upper 
right-hand corner of the screen while the recording session is in 
progress. Type the keystrokes you want to record. These key- 
strokes are acted upon by Turbo Debugger exactly as if you were 
not recording a macro. 


Once you have finished recording keystrokes, issue the Options | 
Macros | Stop Recording command or its hot key, Alt-Hyphen. You 
can also press the key you assigned the macro to (Alt-M) once 
more. 


Alt = is the hot key for starting to record a macro. 


Stops recording keystrokes that are assigned to a key. Use this - 
command after issuing the Options | Macros | Create command to 
assign keystrokes to a key. 


Alt-Hyphen is the hot key for ending a macro. 


Removes a macro assigned to a single key. You are prompted to 
press the key of the macro you want to delete. 


Removes all keystroke macro definitions and restores all keys to 
the meaning that they originally had. 


This command opens a dialog box in which you can set several 
options that control the appearance of the Turbo Debugger 
display. 
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FI 4. 
| put pent | file len gun Ereakpoints “pti 

The Display Options st pov: e: TPD File: TPDEMO.PAS 217: 
OX 


urite 
end; { riba } 


————f) r) 
> begin { program } * Display swapping... 2°: 
Init; None 


Buffer : := GetLine ©) Smart 
while Buffer > oH a Always 
begin eee ee 
ProcessLine(Buf fer) 
Buffer := GetLine; | 
end; 
ShowResults; 
ParmsOnHeap; 


Display Swapping The Display Swapping radio buttons let you choose from three 
ways of controlling how the User screen gets swapped back and 
forth with Turbo Debugger’s screen: 


None Don’t swap between the two screens. Use this option if 
you're debugging a program that does not output to 
the User screen. 


Smart Swap to the User screen only when display output may 
occur. Turbo Debugger swaps the screens any time that 
you step over a routine, or if you execute an instruction 
or source line that appears to read from or write to 
video memory. This is the default option. 


Always Swap to the User screen every time the user program 
runs. Use this option if the Smart option is not catching 
all the occurrences of your program writing to screen. 
If you choose this option, the screen flickers every time 
you step through your program, since Turbo De- 
bugger’s screen is replaced for a short time with the 
User screen. 
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Integer Format 


Screen Lines 


Tab Size 


Path for Source 
command 


Save Options 
command 


These radio buttons let you choose from three display formats for 
displaying integers: 


Decimal Shows integers as ordinary decimal numbers. 


Hex Shows integers as hexadecimal numbers, displayed in 
a format appropriate to the current language. 


Both Shows integers as both decimal numbers and as hex 
numbers in parentheses after the decimal value. 


These radio buttons are used to determine whether Turbo 
Debugger’s screen uses the normal 25-line display or the 43- or 
50-line display available on EGA and VGA display adapters. 


This input box lets you set how many columns each tab stop 
occupies. You can reduce the tab column width to see more text in 
source files that have a lot of code indented with tabs. You can set 
the tab column width from 1 to 32. 


Sets the directories that Turbo Debugger searches for your source 
files. See the discussion of the Module window in Chapter 8 for 
more information. 


This command opens a dialog box from which you can save your 
current options to a configuration file on disk. These options are 


# your macros 
= the current window layout and pane formats 
@ all settings made in the Options menu 


Turbo Debugger User’s Guide 


Figure 4,2 
The Save Options dialog box 


a 
rit 
end; tal eparostniieas } 
> begin { progran } 
Init 


nits; 

Buffer := GetLine; 

while Buffer = '' do Options 

begin Layout 
ProcessLine(Buf fer); Macros 

Buffer := GetLine; 

nd; SCL) 


end; 
ShowResults; Lei mone 


ParmsOnHeap; 


Turbo Debugger lets you save your options in any or all of these 
ways, depending on which of the Save condemadan check boxes 
you turn on: 


Options Saves all settings made in the Options menu. 
Layout Saves only the windowing layout. 
Macros Saves only the currently defined macros. 


You can also use the Save To input box to change the name of the 
configuration file to which you are saving the options. 


Restore Options 


command Restores your options from a disk file. You can have multiple 
configuration files, containing different macros, window layouts, 
and so forth. You must choose a configuration file that was 
created by the Save Options command or with TDINST. 


Running DOS in Turbo Debugger 


When debugging a program, you sometimes need to use another 
program or utility. Do this via File | DOS Shell. 


When you start the DOS command processor, the program you 
are debugging is swapped to disk if necessary. This lets you 
perform DOS commands even \ while you are debugging a 
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Waming! 


program that takes all the available memory. Of course, this 
means that there may be a few seconds of delay while your pro- 
gram is being swapped to and from the disk. 


Do not load TSRs (terminate and stay resident programs) on top 
of Turbo Debugger while you are shelled to DOS. 


When you have finished issuing commands to DOS, type EXIT and 
press Enter to return to your debugging session. 


4 


Returning to DOS 
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You can end your debugging session and return to DOS at any 
time by pressing Alt-X, except when a dialog box is active (in that 
case, first close the dialog box by pressing Esc). You can also 
choose File | Quit. 


All the memory initially allocated to the program being debugged 
is freed. If the program you are debugging allocates memory via 
the DOS block memory allocation routines, that memory is also 
freed. | 
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Controlling program execution 


When you debug a program, you usually execute portions of it 
and check at a stopping point to see that it is behaving correctly. 
Turbo Debugger gives you many ways to control your program's 
execution. You can 


m execute single machine instructions or single source lines 

m skip over calls to functions or procedures 

m “animate” the debugger (perform continuous tracing) 

w run until the current function or procedure returns to its caller 
B run to a specified location 

w continue until a breakpoint is reached 

m reverse program execution 

A debugging session consists of alternating periods when either 
your program or the debugger is running. When the debugger is 
running, you can cause your program to run by choosing one of 
the Run menu’s command options or pressing its hot key equiva- 
lent. When your program is running, the debugger starts up again 
when either the specified section of your program has been exe- 


cuted, or you interrupt execution with a special key sequence, or 
Turbo Debugger encounters a breakpoint. 


This chapter shows you how to examine the state of your pro- 
gram whenever Turbo Debugger is in control. You'll see various 
ways to execute portions of your program, and also how to inter- 
rupt your program while it’s running. Finally, you’ll learn the 
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ways you can restart a debugging session, either with the same 
program or with a different program. 


Examining the current program state 
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The Variables 
window 


Figure 5.1 
Tne Variables window 


The “state” of your program consists of the following elements: 


w its DOS command-line arguments 
m the stack of active functions or procedures 
m the current location in the source code or machine code 
m register values 
w the contents of memory 
w the reason the debugger stopped your program 
mw the value of your program data variables 
The following sections explain how to use the Variables window, 
the Stack window, the local menus of the Global and Static panes, 
and the Origin and Get Info commands. See Chapter 6 for more 


information on how to examine and change the values of your 
program data variables. 


You open the Variables window by choosing View| Variables. 
This window shows you all the variables (names and values) that 
are accessible from the current location in your program. Use it to 
find variables whose names you can’t remember. You can then 
use the local menu commands to further examine or change their 
values. You can also use this window to examine the variables 
local to any function that has been called. 
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cy 


The Global pane local 
menu 


Inspect 
Change 


See Chapter 6 for more 
Information on how Inspector 
windows behave. 


When you’re debugging a Turbo Pascal program, the variables 
won't be arranged alphabetically. 


You open a Variables window by choosing View| Variables. A 
Variables window has two panes: 


a The Global pane (top) shows all the global symbols in your 
program. 

n The Static pane (bottom) shows all the static symbols in the 
current module (the module containing the current program 
location, CS:IP) and all the symbols local to the current 
function. 


Both panes show the name of the variable at the left margin and 
its value at the right margin. If Turbo Debugger can’t find any 
data type information for the symbol, it displays four question 
marks (????). 


Press Alt-F10 (as with all local menus) to pop up the Global pane’s 
local menu. If control-key shortcuts are enabled, you can also 
press Ctrl with the first letter of the desired command to access it. 


If your program contains functions that perform recursive calls, or 
if you want to view the variables local to a function that has been 
called, you can examine the value of a specific instance of a func- 
tion’s local data. First create a Stack window with View | Stack, 
then move the highlight to the desired instance of the function 
call. Next, press Alt-F10 and choose Locals. The Static pane of the 
Variables window then shows the values for that specific instance 
of the function. 


This local menu consists of two commands: Inspect and Change. 


Inspect 


Opens an Inspector window that shows you the contents of the 
currently highlighted global symbol. 


If the variable you want to inspect is the name of a function, you 
are shown the source code for that function, or if there is no 
source file, a CPU window shows you the disassembled code. 


If the variable you inspect has a name that is superseded by a 
local variable with the same name, you’ll see the actual value of 
the global variable, not the local one. This characteristic is slightly 
different than the usual behavior of Inspector windows, which 
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See Chapter 9 for more 
information on assignment 
and data type conversion. 


The Static pane local 
menu 


Inspect 
Change 


See Chapter 6 for more 


Information on how Inspector 
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windows behave. 


See Chapter 9 for more 
information on assignment 
and data type conversion. 


normally show you the value of a variable from the point of view 
of your current program location (CS:IP). This difference gives 
you a convenient way of looking at the value of global variables 
whose names are also used as local variables. 


Change 


Changes the value of the currently selected (highlighted) global 
symbol to the value you enter at the Change dialog box. Turbo 
Debugger performs any necessary data type conversion exactly as 
if the assignment operator for your current language had been 
used to change the variable. 


You can also change the value of the currently highlighted symbol 
by opening the Inspector window and typing a new value. When 
you do this, the same dialog box appears as if you had first 
specified the Change command. 


Press the Alt-F10 key combination to pop up the Static pane’s local 
menu; if control-key shortcuts are enabled, use the Ctrl key with 
the first letter of the desired command to access it. 


The Static pane has these two local menu commands: Inspect and 
Change. 


Inspect 


Opens an Inspector window that displays the contents of the 
currently highlighted module’s local symbol. 


Change 


Changes the value of the currently selected (highlighted) local 
symbol to the value you enter at the Change dialog box. Turbo 
Debugger performs any data type conversion necessary, exactly as 
if the assignment operator for your current language had been 
used to change the variable. 


You can also change the value of the currently highlighted symbol 
by opening the Inspector window (see previous command) and 
starting to type a new value. When you do this, the same dialog 
box appears as if you had first specified the Change command. 
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The Stack window 


Figure 5.2 
The Stack window 


The Stack window local 
menu 


Inspect 
Locals 


You create a Stack window by choosing View | Stack. The Stack 
window lists all active functions or procedures. The most recently 
called routine is displayed first, followed by its caller and the 
previous caller, all the way back to the first function or procedure 
in the program (the main program in Pascal; in C programs, 
usually the function called main). For each procedure or function, 
you see the value of each parameter it was called with. 


[=]=Stack 


The Stack window likewise displays the names of object methods 
or class member functions, prefixed with the name of the object or 
class type that defines the method or member function: 


SHAPES .ACIRCLE(174, 360, 75.0) {Turbo Pascal} 


Press Alt-F10 to pop up the Stack window local menu, or press Ctr 
with the first letter of the desired command to access it. 


The Stack window local menu has two commands: Inspect and 
Locals. 


Inspect 


Opens a Module window positioned at the active line in the 
currently highlighted function. If the highlighted function is the 
top (most recently called) function, the Module window shows 
the current program location (CS:IP). If the highlighted function is 
one of the functions that called the most recent function, the 
cursor is positioned on the line in the function that will be 
executed after the called function returns. 


You can also invoke this command by positioning the highlight 
bar over a function, then pressing Enter. 


Locals 


Opens a Variables window that shows the symbols local to the 
current module, as well as the symbols local to the currently high- 
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The Origin local 
menu command 


The Get Info 
command 


lighted function. If a function calls itself recursively, there are 
multiple instances of the function in the Stack window. By posi- 
tioning the highlight bar on one instance of the function, you can 
use this command to look at the local variables in that instance. 


Both the Module window and the Code pane of a CPU window 
have an Origin command on their local menus. Origin positions 
the cursor at the current code segment (CS:IP). This is very useful 
when you have been looking at your code and want to get back to 


where your program stopped. 


You can choose File | Get Info to look at memory use and to 
determine why the debugger gained control. This and other 
information appears in a text box (see Figure 0) that disappears 
with your next keystroke: 

m The name of the program you're debugging. 

w A description of why your program stopped. 


= The amount of memory used by DOS, Turbo Debugger, and 
your program. 


w If you have EMS memory, its use appears to the right of main 
memory use. 


= A list of interrupts intercepted by the program you're 
debugging. 


= The DOS version you're running. 


= Whether breakpoints are handled entirely in software or if they 
have hardware assistance. 
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Figure 5.3 
The Get Info text box 


.—— Memory EMS 
| DOS :139Kb DOS ~:~. 32Kb], 
i) Debugger -: - Debugger : . 272Kb |i 

Program : 16Kb |: 
Available: ~2016Kb |: 


User interrupts: 00h 1Bh 23h 24h 
DOS version. ee 4.00- 
Breakpoints : Hardware 
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Here are the messages you'll see on the second (status) line, 
describing why your program stopped: 


Stopped at__ 

Your program stopped as the result of a completed Run | Execute 
To, Run | Go to Cursor, or Run | Until Return command. This 
status line message also appears when your program is first 
loaded, and the compiler startup code in your program has been 
executed to put you at the start of your source code. 


No program loaded 

You started Turbo Debugger without loading a program. You 
cannot execute any code until you either load a program or 
assemble some instructions using the Assemble local menu 
command in the Code pane of a CPU window. 


Control! Break 
You interrupted execution of your program with Ctrl-Break. 


Trace 
You executed a single source line or machine instruction with F7 
(Run | Trace). 


Breakpoint at ___ 

Your program encountered a breakpoint that was set to stop your 
program. The text after “at” is the address in your program where 
the breakpoint occurred. 


Terminated, exit code ___ 

Your program has finished executing. The text after “code” is the 
numeric exit code returned to DOS by your program. If your pro- 
gram does not explicitly return a value, a garbage value may be 
displayed. You cannot run your program until you reload it with 
Run | Program Reset. 
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Loaded 

You loaded Turbo Debugger and specified a program and the 
option that prevents the compiler startup code from executing. 
No instructions have been executed at this point, including those 
that set up your stack and segment registers. This means that if 
you try to examine certain data in your program, you may see 
incorrect values. 


Step 
You executed a single source line or machine instruction, skipping 
function calls, with F8 (Run | Step Over). 


Interrupt 

You pressed the interrupt key (usually Ctrl-Break) to regain control. 
Your program was interrupted and control passed back to the 
debugger. 


Exception __ 

You were using TD386, and a processor exception has occurred. 
This usually happens when your program attempts to execute an 
illegal instruction opcode. The Intel processor documentation 
describes each exception code in complete detail. 


Hardware device driver stuck 

You were using a hardware debugger and set a hardware break- 
point in a stack variable that is conflicting with Turbo Debugger. 
You must remove the hardware breakpoint before you proceed. 


Divide by zero 
Your program has executed a divide instruction where the 
dividend is zero. 


Global breakpoint _ at __ 

A global breakpoint has been triggered. You are told the 
breakpoint number and the location in your program where the 
breakpoint occurred. 


The Run menu 


The Run menu has a number of options for executing different 
parts of your program. Since you use these options frequently, 
they are all available on function keys. 
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Run 


Go to Cursor 


Trace Into 


Step Over 


Run 

Go to cursor 

Trace into 

Step over 

Execute to... 

Until return 

Animate... 

Back trace Alt-F4 
Instruction trace Alt-F7 


Arguments... 
Program rese 


Ctri-F2 


Runs your program at full speed. Control returns to the debugger 
when one of the following events occurs: 


Your program terminates. 
a A breakpoint with a break action is encountered. 
o You interrupt execution with Citrl-Break. 


Executes your program up to the line that the cursor is on in the 
current Module window or CPU Code pane. If the current 
window is a Module window, the cursor must be on a line of 
source code. 


Executes a single source line or assembly level instruction. If the 
current window is a Module window, a single line of source code 
is executed; if it’s a CPU window, a single machine instruction. If 
the current line contains any procedure or function calls, Turbo 
Debugger traces into the routine. However, if the current window 
is a CPU window, only a single machine instruction is executed. 


Turbo Debugger treats object methods and class member func- 
tions just like any other procedure or function. F7 traces into the 
source code if it’s available. 


Executes a single source line or machine instruction, skipping 
over any procedure or function call(s). If the current window is a 
Module window, this command usually executes a single source 
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Execute To... 
Until Return 


Alt 


line. However, if the current window is a CPU window, only a 
single machine instruction is executed. 


If you step over a single source line, Turbo Debugger treats any 
function or procedure call(s) in that line as part of the line. You 
don’t end up at the start of one of the functions. Instead, you end 
up at the next line in the current routine or at the previous routine 
that called the current one. 


If you are in a CPU window, Turbo Debugger treats certain 
instructions as a single instruction, even when they cause mul- 
tiple assembly instructions to be executed. Here is a complete list 
of the instructions Turbo Debugger treats as single instructions: 


CALL Subroutine call, near, and far 
INT Interrupt call 

LOOP Loop control with CX counter 
LOOPZ Loop control with CX counter 
LOOPNZ Loop control with CX counter 


Also stepped over are REP, REPNZ, or REPZ followed by CMPS, 
CMPS, CMPSW, LODSB, LODSW, MOVS, MOVSB, MOVSW, SCAS, 
SCASB, SCASW, STOS, STOSB, or STOSW. 


The Run | Step Over command treats a call to an object method or 
a class member function like a single statement, and steps over it 
like any other procedure or function call. 


Executes your program until the address you specify in the dialog 
box is reached. The address you specify may never be reached if a 
breakpoint action is encountered first, or if you interrupt 
execution. 


Executes until the current function returns to its caller. This is 
useful in two circumstances: When you have accidentally exe- 
cuted into a function or procedure that you are not interested in 
with Run | Trace instead of Run| Step, or when you have deter- 
mined that the current function works to your satisfaction, and 
you don’t want to slowly step through the rest of it. 


Turbo Debugger User's Guide 


Animate... 


Performs a continuous series of Trace Into commands, updating 
the screen after each one. (The effect is to run your program in 
slow motion.) You can watch the current location in your source 
code and see the values of variables changing. You interrupt this 
command by pressing any key. 


After you choose Run | Animate, you will be prompted for a time 
delay between successive traces. The time delay is measured in 
tenths of a second; the default is 3. 


Back Trace 


If you are tracing (F7 or Alt-F7) through your program, reverses the 
order of execution. This is handy if you trace beyond the point 

Alt where you think there may be a bug, and want to reverse 
program execution back to that point. This lets you “undo” the 
execution of your program by stepping backward through the 
code, either a single step at a time or to a specified point 
highlighted in the Instructions pane of the Execution History 
window. 


Waming! Some restrictions apply. See the section, “The Instructions pane 
(page 86).” 


Instruction Trace 


Executes a single machine instruction. Use this when you want to 
trace into an interrupt, or when you’re ina Module window and 

Alt you want to trace into a procedure or function that’s ina module 
with no debug information (for example, a library routine). 


Since you will no longer be at the start of a source line, this 
command usually places you in a CPU window. 


Argumenis... 


This command lets you set new command-line arguments for 
your program. This is discussed more in Chapter 5. 
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Program Reset 


Reloads from disk the program you're debugging. Use this when 
you've executed past the place where you think there is a bug. 


If you’re in a Module or CPU window, the debugger won’t return 
to the start of the program. Instead, you'll stay exactly where you 
were when you chose the Program Reset command. If you chose 
Program Reset because you just executed one source statement 
more than you intended, you can position the cursor up a few 
lines in your source file and press F4 to run to that location, or 
choose Run | Back Trace to step back through previously executed 
code instead of choosing Program Reset. 


The Execution History window 


Figure 5.4 


The Execution History window 
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The Instructions 
pane 


Turbo Debugger has a special feature called the execution history 
that keeps track of each instruction as it is executed (provided you 
are tracing into the code), and also, if you want, records the key- 
strokes you input to get to a given point in your program. You 
can examine these instructions, and also undo them to return to a 
point in the program where you think there might be a bug. If you 
don’t have EMS memory, Turbo Debugger can record about 400 
instructions. If you have EMS, it can record approximately 3000 
instructions. 


=[8}=Execution history——————3-[t] [VJ = 
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You can examine the execution history in the Execution History 
window, which you open by choosing View | Execution History. 


This window has two panes: the Instructions pane on top and the 
Keystroke Recording pane on the bottom. 


The Instructions pane shows instructions already executed that 
you can examine or undo. Use the highlight bar to make your 
selection. 
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[> The execution history only keeps track of instructions that have 
been executed with the Trace Into command (F7) or the Instruction 
Trace command (Alt-F7). It also tracks for Step Over, as long as you 
don’t encounter one of the commands listed on page 84. As soon 
as you use the Run command or execute an interrupt, the 
execution history is deleted. (It starts being recorded again as 
soon as you go back to tracing.) 


E> You cannot backtrace into an interrupt call. 


> Ifyou step over a procedure or function call, you will not be able 
to trace back beyond the instruction following the return. 


C.> Backtracing through a port-related instruction has no effect, since 
you can’t undo reads and writes. 


The Instructions pane =‘ The local menu for the Instructions pane contains three 
local menu _ instructions: 


Inspect 
Reverse execute Inspect 


Full history This command takes you to the command highlighted in the 
Instructions pane. If it is a line of source code, you are shown that 
line in the Module window; if there is no source code, the CPU 
window opens, with the instruction highlighted in the Code pane. 


Reverse Execute 


The hot key for this This command reverses program execution to the location 

command's AltF4. highlighted in the Instructions pane. If you selected a line of 
source code, you are returned to the Module window; otherwise, 
the CPU window appears with the highlight bar of the Code pane 
on the instruction. 


Waming! ‘You can never reverse back over a section of your program that 
you didn’t trace through. For example, if you set a breakpoint and 
then pressed F9 to run until the breakpoint was reached, all your 
reverse execution history will be thrown away. In this case, if you 
want to recover, you can use the keystroke replay facility of the 
Execution History window to reload your program and run 
forward to that point. 


Waming! The INT instruction causes any previous execution history to be 
thrown out. You can’t reverse back over this instruction, unless 
you press Alt-F7 to trace into the interrupt. 
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The Keystroke 
Recording pane 


The Keystroke 


Recording pane local 
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menu 


The following instructions do not cause the history to be thrown 
out, but they cannot have their effects undone. You should be on 
the lookout for unexpected side effects if you back up over these 
instructions: 


IN INSW 

OUT OUTSB 

INSB OUTSW 
Full History 


This command is a toggle. If it is set to On, backtracing is enabled. 
If it is Off, backtracing is disabled. 


Even if you do inadvertently destroy your execution history, you 
can quickly execute back to a given point in your program, if you 
have keystroke recording enabled. 


Keystroke recording works in conjunction with the reverse pro- 
gram execution capability to give you different ways of recover- 
ing to a previous point in your debugging session. It keeps a 
record of all the keys that you press, both when you’re issuing 
commands to Turbo Debugger and when you’re interacting with 
the program you are debugging. The keystrokes are recorded in a 
file named PROGNAME.TDK, where progname is the name of the 
program you are debugging. 


Use the bottom pane of the Execution History window to replay 
keystrokes and recover to a previous point in your session. Each 
line in the keystroke history list shows the reason that Turbo 
Debugger gained control (breakpoint, trace, and so forth) and 
your programs current location at that time. If the location corre- 
sponds to a line of source code, that line is displayed. Otherwise, 
the instruction at that address is disassembled. 


The -k command-line option enables keystroke recording. (See 
page 65.) You can also use TDINST to set the default to On. 


The local menu for the Keystroke Recording pane contains two 
commands: Inspect and Keystroke Restore. 
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Inspect 
Keystroke restore 


Inspect 


If you highlight a line in the Keystroke Recording pane, then 
choose Inspect from the local menu, the Module window comes 
up with the cursor on the line of source code at which that key- 
stroke occurred. 


If this line does not correspond to a source code position, the CPU 
window opens with the highlight positioned on the instruction. 


Keystroke Restore 


If you highlight a line in the Keystroke Recording pane, then 
choose Keystroke Restore, Turbo Debugger reloads your program 
and runs it to the highlighted context. This is especially useful if 
you have executed a Turbo Debugger command that has deleted 
your execution history. 


Interrupting program execution 


Ctrl-Break 


With interactive programs, the quickest way to get to a specific 
place in your program is sometimes to simply run it, interact with 
it until it gets to the desired part of the code, and then interrupt 
execution. This is particularly true if the piece of code you want to 
examine is called several times before the one time of particular 
interest to you. 


You may also want to interrupt program execution when, for 
some unexpected reason, control does not return to the debugger. 
This can happen when a piece of code contains an infinite loop: 
You expect a piece of code to be executed, so you set a breakpoint, 
but the breakpoint is never reached. 


This key combination will almost always interrupt your program 
and return control to the debugger. It takes effect as soon as you 
press it, So you might sometimes appear to be in an unexpected 
piece of code. This code could be in the ROM keyboard BIOS if 
your program is waiting for a keystroke, or at any instruction in 
the loop being executed. Ctrl-Break is unable to override the follow- 
ing two conditions—if either of these conditions occur, you will 
need to reboot your system: 
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m You are stuck in a loop with interrupts disabled. 
u The system has crashed due to execution of erroneous code. 


If you are debugging a program that needs to act upon the Crtr- 
Break key combination itself, you can change the interrupt key. 
Use the TDINST installation program. You can set the interrupt 
key to be any key combination. 


Program termination 


When your program terminates and exits back to DOS, Turbo 
Debugger regains control. It displays a message showing the exit 
code that your program returned to DOS. Once your program 
terminates, you cannot use any of the Run menu options until you 
reload the program with Run | Program Reset. 


The segment registers and stack are usually not correct when your 
program has terminated, so do not examine or modify any pro- 
gram variables after termination. 


Restarting a debugging session 
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Reloading your 
program 


Turbo Debugger has several features that make restarting a de- 
bugging session as painless as possible. When you’re debugging a 
program, it’s easy to go just a little too far and overshoot the real 
cause of the problem. In that case, Turbo Debugger lets you 
restart debugging but suspends execution before the last few 
commands that caused you to miss the problem that you wanted 
to observe. 


Most debuggers force you to type in manually what could be a 
very long sequence of commands to get back to the place where 
the error occurred. Turbo Debugger has the powerful capability to 
record the keystrokes that made up the last session and to replay 
them on demand. It also lets you reload your last program from 
disk, with its previous DOS command-line arguments. 


To reload the program you were debugging, choose Run | Pro- 
gram Reset. Turbo Debugger reloads the program from disk, with 
any data you have added since you last saved to disk. This is the 
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safest way to restart a program. Restarting by executing at the 
start of the program can be risky, since many programs expect 
certain data to be initialized from the disk image of the program. 
Note that Program Reset leaves breakpoints and watchpoints intact. 


Keystroke macro 


recording and _ You can use the keystroke macro facility to record keystroke 
playback sequences that you use frequently. During debugging, you often 
repeat the same sequence of commands to get to a certain place in 
your program. This can be very tedious. 


To get around this problem, you can define a keystroke macro 
that records all the keys you press, from when you first start 
Turbo Debugger until you have your program in the desired 
state. At that point, you can stop recording keystrokes. If you 
have to get back to the same place in your program, all you have 
to do is replay the keystroke macro. 


C> Youcan’t use this utility to record keystrokes that must be typed 
to your program. You can only record Turbo Debugger command 
keystrokes. 


The first thing you must do after starting Turbo Debugger from 
DOS is define a keystroke macro. Choose Options | Macros | Create 
to do this. You’re prompted to press a key to assign the keystroke 
macro to. Choose a key that hasn’t been assigned to a function 
yet, such as Shiftand one of the function keys, say Shift-F1. Now 
take your program to its point of crashing. 


At that point, stop recording the keystroke macro by choosing 
Options | Macros | Stop Recording. Save the macro to disk by 
choosing the Options | Save Options command and turning on the 
Macros option in the Save Configuration dialog box. Continue 
running your program. After your program crashes, and you 
have reloaded it and Turbo Debugger, you can simply press Shift- 
F1 to restart the program. 


If your program requires you to type things to get to the next part 
of the recorded command sequence, you still have to enter those 
keystrokes manually. (You can do this while the macro is 
running.) For programs that do not require you to enter anything, 
this keystroke recording mechanism can completely automate the 
restarting procedure, saving many keystrokes. 


C> Whena macro is saved to a configuration file, the configuration of 
the total environment is saved, including opened and zoomed 
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windows. Thus if you record a macro that opens a window and 
don’t close the window before saving the macro, the next time 
you restore that configuration file, the window will be open 
automatically even though you haven't executed the macro. 


Opening a new program to debug 


You load a new program to debug by choosing File | Open to open 
the Load Program dialog box. 
Figure 5.5 p 


The Load Program dialog 
box 


4 
Ce 
Tirectories 
: im pepper | Cancel_» 
donut in.exe td ee 
| Help» 

Se 


dototal .exe tdold 
drwhappy.exe 
echo.exe 
hello.exe 
little.exe 
mytest.exe 
img reverse .exe 
small .exe 
tcdemo.exe 


Bs WEE TES OE BUG EROS: EXE 
BILDSP.EXE Feb 19, 1988 2:23pm 4592 bytes 


You can enter a file name (extension .EXE) in the File Name input 
box, or press Enter to active a list box of all the .EXE files in the 
current directory. Move the highlight bar to the file you want to 
load and press Enter. 


If, instead, you type in the name of the file you want to load, the 
highlight bar moves to the file that begins with the first letter(s) 
you typed. When the bar is positioned on the file you want, press 
Enter. 


You can supply arguments to the program to debug by placing 
them after the program name, exactly as you would at the DOS 
prompt: 


myprog abc 


This loads program MyProg with three command-line arguments, 
a,b, and c. 
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Changing the program arguments 


If you forgot to supply some necessary arguments to your pro- 
gram when you loaded it, you can use the Run | Arguments 
command to set or change the arguments. Enter new arguments 
exactly as you would following the name of your program on the 
DOS command line. 


Once you have entered new arguments, Turbo Debugger asks you 
if you want to reload your program from disk. You should 
answer Yes, because for most programs, the new arguments will 
only take effect if you reload the program first. 
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Examining and modifying data 


Turbo Debugger provides a unique and intuitive way to examine 
and even change your programs data. 


o Inspector windows let you look at your data as it appears in 
your source file. You can “follow” pointers, scroll through 
arrays, and see structures, records, and unions exactly as you 
wrote them. 


o You can also put variables and expressions into the Watches 
window, where you can watch their values as your program 
executes. 


a The Evaluate/ Modify dialog box shows you the contents of any 
variable and lets you assign a new value to it. 


This chapter assumes that you understand the various data types 
that can be used in the language you're using (C, Pascal, or 
assembler). If you are fairly new to a language and have not yet 
explored all its data types (char, int, integer, Boolean, real, single- 
and double-precision floating point, string, long integer, and so 
on), this chapter can still give you valuable information about 
them. When you have delved into the more complex data types 
(arrays, pointers, records, structures, unions, and so on), return to 
this chapter to learn more about looking at them with Turbo 
Debugger. 


For how to examine or Tn this chapter, we show you how to examine and modify vari- 
Pasa pee re a, one. ables in your program. First, we explain the Data menu and its 
see Chapter 11, Options. We then discuss how you can modify program data by 


evaluating expressions that have side effects, and show you how 
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to point directly at data items in your source modules. Finally, we 
introduce the Watches window and describe the way that the data 
types of each language appear in Inspector windows. 


The Data menu 


Tnanect The Data menu lets you choose how to examine and change pro- 
Evaluate/modify... Ctrl-F4 | gram data. You can evaluate an expression, change the value of a 


Add watch. 7 trl-F7 | variable, and open Inspector windows to display the contents of 


your variables. 


Inspect... 


Prompts you for the variable that references the data you want to 
inspect, then opens an Inspector window that shows the contents 
of the program variable or expression. You can enter a simple 
variable name or a complex expression. 


If the cursor is on a variable in a text pane when you issue this 
command, the dialog box automatically contains the variable at 
the cursor, if any. If you select an expression in a text pane (using 
Ins), the dialog box contains the selected expression. 


Inspector windows really come into their own when you want to 
examine a complicated data structure, such as an array of 
structures or a linked list of items. Since you can inspect items 
within an Inspector window, you can “walk” through your pro- 
gram’s data objects as easily as you scroll through your source 
code in the Mcdule window. 


CL See the “Inspector windows” section later in this chapter for a 
complete description of how Inspector windows behave. 


Evaluate/ 


Modify... Opens the Evaluate/Modify dialog box (Figure 6.1), which 
See Chapter 9 fora prompts you for an expression to evaluate, then evaluates it, 
complete discussion of exactly as the compiler would during compilation when you 
expressions. choose the Eval button. 


If the cursor is in a text pane when you issue this command, the 
dialog box automatically contains the variable at the cursor, if 
any. If you select an expression (using Ins), the dialog box contains 
the marked expression. 
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Figure 6.1 
The Evaluate/Modify dialog 
box 
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____ See Chapter? fora Remember that you can add a format control string after the 

discussion of format control. expression that you want to watch. Turbo Debugger displays the 
result in a format suitable for the data type of the result. To 
display the result in a different format, put a comma (,) separator, 
then a format control string after the expression. This is useful 
when you want to watch something but have it displayed ina 
format other than Turbo Debugger’s default display format for the 
data type. 


The dialog box has three fields. You type the expression you want 
to evaluate in the top one. This is the Evaluate input box, and it 
has a history list just like any other input box. The middle field 
displays the result of evaluating your expression. The bottom 
field is an input box where you can enter a new value for the 
expression. If the expression can’t be modified, this box reads <Not 
available>, and you can’t move your cursor into it. 


Your entry in the New Value input box takes effect when you 
choose the Modify button. Use Tab and Shift-Tab to move from one 
box to another, just as you do in other dialog boxes. Press Esc from 

fea inside any input box to remove the dialog box, or click the Cancel 
button with your mouse. 


Data strings too long to display in the Result input box are termi- 
nated by an arrow (>). You can see more of the string by scrolling 
to the right. 


If you are debugging a C++ or object-oriented Pascal program, the 
Evaluate/ Modify dialog box also lets you display the fields of an 
object instance or the members of a class instance. You can use 
any format specifier with an instance that can be used in 
evaluating a record. 


When you're tracing inside a method or member function, Turbo 
Debugger knows about the scope and presence of the Self/this 
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You cannot execute 
constructor or destructor 
methods or member 
functions in the Evaluate 
window. 


C programmers 


parameter. You can evaluate Self/this and follow it with format 
specifiers and qualifiers. 


Turbo Debugger also lets you call a method or member function 
from inside the Evaluate/ Modify dialog box. Just type the 
instance name followed by a dot, followed by the method or 
member function name, followed by the actual parameters (or 
empty parentheses if there are no parameters). With these 
declarations, 


type 
Point = object 

X, Y : Integer; 

Visible : Boolean; 

constructor Init (InitX, InitY : Integer); 

destructor Done; virtual; 

procedure Show; virtual; 

procedure Hide; virtual; 

procedure MoveTo(NewX, NewY : Integer); 
end; 


var 
APoint : Point; 


you could enter any of these expressions in Turbo Debugger’s 
Evaluate window: 


Expression Result 

APoint.X 5 ($5) : Integer 
APoint (5,23,FALSE) : Point 
APoint.MoveTo @6F4F : OOBE 
APoint.MoveTo(10, 10) calls method MoveTo 
APoint.Show() calls method Show 


The C language has a feature called expressions with side effects that 
can be powerful and convenient, as well as a source of surprises 
and confusion. 


An expression with side effects alters the value of one or more 
variables or memory areas when it is evaluated. For example, the 
C increment (++) and decrement (- -) operators and the assign- 
ment operators (=, +=, and so on) have this effect. If you execute 
functions in your program within a C expression (for example, 
myfunc(2)), note that your function can have unexpected side 
effects. 


If you don’t intend to modify the value of any variable but merely 
want to evaluate an expression containing some of your program 
variables, don’t use any of the operators that have side effects. On 
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the other hand, side effects can be a quick and easy way to change 
the value of a variable or memory area. For example, to add 1 to 
the value of your variable named count, evaluate the C expression 
count++. 


You can also use the Evaluate/ Modify dialog box as a simple 
calculator by typing in numbers as operands instead of program 
variables. 


Add Watch... 


Prompts you for an expression to watch, then places the expres- 
sion or program variable on the list of variables displayed in the 
Watches window when you press Enter or choose the OK button. 


If the cursor is in a text pane when you issue this command, the 
dialog box automatically contains the variable at the cursor, if 
any. If you select an expression (using /ns), the dialog box contains 
the selected expression. 


Function Return 


Shows you the value the current function is about to return. Use 
this command only when the function is about to return to its 
caller. 


The return value is displayed in an Inspector window, so you can. 
easily examine return values that are pointers to compound data 
objects. 


This command saves you having to switch to a CPU window to 
examine the return value that is placed in the CPU registers. And 
since it also knows the data type being returned and formats it 
appropriately, it is much easier to use than a hex dump. 


Pointing at data objects in source files 


_ See Chapter 8 fora full Turbo Debugger has a powerful mechanism to relieve you from 
GBCUSS Ol" OF reaps always typing in the names of program variables that you want to 
' inspect. From within any Module window, you can place the 
cursor anywhere within a variable name and use the local menu 
Inspect command to create an Inspector window showing the 
contents of that variable. You can also select an expression or 
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variable to inspect by pressing Ins and using the cursor keys to 
highlight it before choosing the Inspect command. 


The Watches window 


Figure 6.2 
The Watches window 
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scopes and when a variable 
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or parameter & valid. 


Waming! 


The Watches window lets you list variables and expressions in 
your program whose values you want to track. You can watch the 
value of both simple variables (such as integers) and complex 
data objects (such as arrays). In addition, you can watch the value 
of a calculated expression that does not refer directly to a memory 
location. For example, x * y + 4. 
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Choose View | Watches to access the Watches window. It holds a 
list of variables or expressions whose values you want to watch. 
For each item, the variable name or expression appears on the left 
and its data type and value on the right. Compound values like 
arrays and structures appear with their values between braces ({ }) 
for C programs, and between parentheses for Pascal programs. If 
there isn’t room to display the entire name or expression, it is 
truncated. 


When you enter an expression to be watched, feel free to use 
variable names that are not yet valid because they are ina 
function that has not yet been called. This lets you set up a watch 
expression before its scope becomes active. This is the only 
situation in Turbo Debugger where you can enter an expression 
that cannot be immediately evaluated. 


This means that if you mistype the name of a variable, the mistake 
won't be detected because Turbo Debugger assumes it is the name 
of a variable that becomes available as your program executes. 


Unless you use the scope-overriding mechanism discussed in 
Chapter 9, Turbo Debugger evaluates expressions in the Watches 
window in the scope of the current location where your program 
is stopped. Hence an expression in the Watches window is 
evaluated as if it appeared in your program at the place where the 
program is stopped. If a watch expression contains a variable 
name that is not accessible from the current scope—for example, if 
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The Watches 
window local 
menu 


Watch... 


Edit... 


Watch... 
Edit... 
Remove 


Delete all 


Inspect 
Change 


Remove 


Delete All 


Inspect 


Change 


See Chapter 9 for more 
information on the 
assignment operator and 
type conversion (casting). 


it's private to another module—the value of the expression is 
undefined and is displayed as four question marks (????). 


When you're tracing inside an object method, you can add the 
Self/this parameter to the Watches window. 


As with all local menus, press Alt-F10 to pop up the Watches 
window local menu. If you have control-key shortcuts enabled, 
press Ctrl with the first letter of the desired command to access it. 


Prompts you for the variable name or expression to add to the 
Watches window. It is added to the beginning of the list. 


Opens a dialog box in which you can edit an expression in the 
Watches window. You can change any watch expression that’s 
there, or enter a new one. 


You can also invoke this command by pressing Enter once you've 
positioned the highlight bar over the watch expression you want 
to change. Press Enter or choose the OK button to put the edited 
expression into the Watches window. 


Removes the currently selected item from the Watches window. 


Removes all the items from the Watches window. This command 
is useful if you move from one area of your program to another, 
and the variables you were watching are no longer relevant. 
(Then use the Watch command to enter more variables.) 


Opens an Inspector window to show you the contents of the 
currently highlighted item in the Watches window. If the item is a 
compound object (array, record, or structure), this lets you view 
all its elements, not just the ones that fit in the Watches window. 
(The section “Inspector windows” on page 102 explains all about 
Inspector windows.) 


Changes the value of the currently highlighted item in the 
Watches window to the value you enter in the dialog box. If the 
current language you are using permits it, Turbo Debugger 
performs any necessary type conversion exactly as if the appro- 
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priate assignment operator (= or :=) had been used to change the 
variable. 


Inspector windows 


An Inspector window displays your program data appropriately, 
depending on the data type you're inspecting. Inspector windows 
behave differently for scalars (for example, char or Int), pointers 
(char * in C, 4 in Pascal), arrays (long x[4], array [1..10] of Word), 
functions, structures, records, unions, and sets. 


The Inspector window lists the items that make up the data object 
being inspected. The title of the window shows the data type of 
the inspected data and its name, if there is one. 


The first item in an Inspector window is always the memory 
address of the data item being inspected, expressed as a segment: 
offset pair, unless it has been optimized to a register or is a 
constant (for example, 3). 


To examine the contents of an Inspector window as raw data 
bytes, select the View | Dump command while you’re in the 
Inspector window. The Dump window comes up, with the cursor 
positioned to the data displayed in the Inspector window. You 

@e can return to the Inspector window by closing the window with 
the Window | Close command (Alt-F3), or clicking the close box 
with your mouse. 


The following sections describe the different Inspector windows . 
that can appear for each of the languages supported by Turbo 
Debugger: C, Pascal, and assembler. The programming language 
used dictates the format of the information displayed in Inspector 
windows. Data items and their values always appear in a format 
similar to the one they were declared with in the source file. 


Remember that you don’t have to do anything special to cause the 
different Inspector windows to appear. The right one appears 
automatically, depending on the data you’re inspecting. 
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C data Inspector 
windows 


scalars Scalar Inspector windows show you the value of simple data 
items, such as 


char x = 4; 
unsigned long y = 123456L; 


Following the top line, these Inspector windows have only a 
single line of information that gives the address of the variable. To 
the left on the following line appears the type of the scalar 
variable (char, unsigned long, and so forth), and to the right 
appears its present value. The value can be displayed as decimal, 
hex, or both. It’s usually displayed first in decimal, with the hex 
values in parentheses (using the standard C hex prefix of 0x). Use 
TDINST to change how the value is displayed. 


If the variable being displayed is of type char, the equivalent 
character is also displayed. If the present value does not have a 
printing character equivalent, use the backslash (\) followed by a 
hex value to display the character value. This character value 
appears before the decimal or hex values. 


=] ti rdcount=3=(1] (WJ> 
rece 


A C scalar Inspector window 


Pointers Pointer Inspector windows show you the value of data items that 
point to other data items, such as 


char *p = “abc"; 

int *ip = 0; 

int **ipp = &ip; 
Pointer Inspector windows usually have a top line that contains 
the address of the variable, followed by a single line of informa- 
tion about the data pointed to. To the left appears [0], indicating 
the first member of an array. To the right appears the value of the 
item being pointed to. If the value is a complex data item, such as 
a structure or an array, however, only as much of it as possible is 
displayed with the values enclosed in braces ({and }). 


If the pointer is of type char and appears to be pointing to a null- 
terminated character string, more information appears, showing 
the value of each item in the character array. To the left in each 
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Figure 6.4 
AC pointer Inspector 
window 


Arrays 


line appears the array index ([1], [2], and so on), and the value 
appears to the right as it would in a scalar Inspector window. In 
this case, the entire string is also displayed on the top line, along 
with the address of the pointer variable and the address of the 
string that it points to. 


You also get multiple lines if you open the Inspector window and 
then use the Range local menu command. This is an important 
technique for C programmers who use pointers to point to arrays 
of items as well as single items. For example, if you had the code 


int array{10]; 
int *arrayp = array; 


and you wanted to look at what arrayp pointed to, use the Range 
local command on arrayp, specifying a start index of 0 and a range 
of 10. If you had not done this, you would only have seen the first 
item in the array. 


—[s] =Inspecting red gg LE 
meres FFBE : ds:0 is DEMO#s 
ru 


*d* 100 Bi : 


Pointer Inspector windows also have a lower pane indicating the 
data type to which the pointer points. 


Array Inspector windows show you the value of arrays of data 
items, such as 


long thread[3] [4] [5]; 
char message[] = “eat these words"; 


There is a line for each member of the array. To the left on each 
line appears the array index of the item. To the right appears the 
value of the item. If the value is a complex data item such as a 
structure or array, as much of it as possible is displayed. 


You can use the Range local menu command to examine any 
portion of an array. This is useful if the array has a lot of elements, 
and you want to look at something in the middle of the array. 
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Figure 6.5 


-=[s]=Inspecting letterinfo-3=[t] [4]= 
A C array Inspector window 68220852 A 
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Structures and unions Structure and union Inspector windows show you the value of 
the members in your structure and union data items. For 
example, 


struct date { 
int year; 
char month; 
char day; 

} today; 


union { 
int small; 
long large; 
} holder; 


These Inspector windows have another pane below the one that 
shows the values of the members. This additional pane shows the 
data type of the member highlighted in the top pane. 


Figure 6.6 [eJ=Inspecting letterinfo[n]=3=(1] [%] 
A C structure or union ue 2 (0x2 
Inspector window 


Structures and unions appear the same in Inspector windows. The 
lower pane of the Inspector window tells you whether you are 
looking at a structure or a union. These Inspector windows have 
as many items after the address as there are members in the struc- 
ture or union. Each item shows the name of the member on the 
left and its value on the right, displayed in a format appropriate 
to its C data type. 


Functions Function Inspector windows show each parameter that a function 
is called with, below the memory address at the top of the 
window. 
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Figure 6.7 =[#J=Inspecting analyzewords=3=[*] [+] 
A C function Inspector E9:02DD 


window et 
They also give you information about the calling parameters, 
return data type, and calling conventions for a function. The 
lower pane indicates the data type returned by the function. 
Pascal data 
Inspector 
windows 


Scalars Scalar Inspector windows show you the value of simple data 
items, such as 


var 
X : Integer; 
Y : Longint; 


These Inspector windows have only a single line of information 
following the top line that gives the address of the variable. To the 
left appears the type of the scalar variable (Byte, Word, Integer, 
Longint, and so forth), and to the right appears its present value. 
The value can be displayed as decimal, hex, or both. It’s usually 
displayed first in decimal, with the hex values in parentheses 
(using the Turbo Pascal hex prefix $). You can use TDINST to 
change how the value is displayed. 


If the variable being displayed is of type Char, the character 
equivalent is also displayed. If the present value does not havea 
printing character equivalent, use a pound sign (#) followed by a 
number to display the character value. This character value 
appears before the decimal or hex values. 
: [=]=Inspecting WordLen=3=[1] [+] 
A Pascal scalar ales ee 
window 


Pointers Pointer Inspector windows in a Pascal program show you the 
value of data items that point to other data items, such as 


var 


IP : “integer; 
LP : ““pointer; 
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Figure 6.9 
A Pascal pointer Inspector 
window 


Arrays 


Figure 6.10 
A Pascal array Inspector 
window 


Records 


Pointer Inspector windows usually have only a single line of 
information following the top line that gives the address of the 
variable. To the left appears [1], indicating the first member of an 
array. To the right appears the value of the item being pointed to. 
If the value is a complex data item such as a record or an array, 
however, only as much of it as possible is displayed, with the 
values enclosed in parentheses. 


You also get multiple lines if you open the Inspector window and 
issue the Range local command, specifying a count greater than 1. 


{"]=Inspecting Temp=3=[f] [+] 
@8810:3EF4 : 8C10:0000 
0003:7500: 

5200:0000 


Array Inspector windows in Pascal programs show you the value 
of arrays of data items, such as 


var 
A: array[1..10,1..20] of Integer; 
B : array[1..50] of Boolean; 


There is a line for each member of the array. To the left on each 
line appears the array index of the item and to the right is its 
present value. If the value is a complex data item such as a record 
or an array, as much of it as possible is displayed, with the values 
enclosed in parentheses. 


You can use the Range command to examine any portion of an 
array. This is useful if the array has a lot of elements, and you 
want to look at something in the middle of the array. 


[sJ=Inspecting LetterTable=3=[*] [s]= 
86706:0058 “A 


Record Inspector windows in Pascal programs show you the 
value of the fields in your records. For example, 


record 
year : Integer; 
month : 1..12; 
day : 1..31; 
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Figure 6.11 
A Pascal record Inspector 
window 


Procedures and 
functions 


Figure 6,12 
A Pascal procedure 
Inspector window 


Assembler data 
Inspector 
windows 


Scalars 


Figure 6.13 
An assembler scalar 
Inspector window 
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end 


These Inspector windows have another pane below the one that 
shows the values of the fields. This additional pane shows the 
data type of the field highlighted in the top pane. 


[s]=Inspecting LetterTable['A']=4=[1] [+] 
@8706:0058 


In the upper pane, procedure and function Inspector windows in 
Pascal programs give you information about calling parameters. 
These windows have a second pane, in which the routine is 
identified as a procedure or function, as well as the data type 
returned by a function. 


{*]=Inspecting ProcessLine=3=[*] [+] 
@8340:0486 - 


S_: BUFFERSIR 


Scalar Inspector windows in assembly language programs show 
you the value of simple data items, such as 


VAR1 DW 99 
MAGIC DT 4.608 
BIGNUM DD 123456 


These Inspector windows have only a single line of information 
following the top line that gives the address of the variable. To the 
left appears the type of the scalar variable (BYTE, WORD, 

DWORD, QWORD, and so forth), and to the right appears its 
present value. The value can be displayed as decimal, hex, or 
both. It’s usually displayed first in decimal, with the hex values in 
parentheses (using the standard assembler hex postfix H). You 
can use TDINST to change how the value is displayed. 


[s]=Inspecting Count=3=[*] [+] 
pee 
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Pointers Pointer Inspector windows in assembler programs show you the 
value of data items that point to other data items, such as 


X DW 0 
XPTR DW X 
FARPTR DD X 


Pointer Inspector windows usually have only a single line of 
information following the top line that gives the address of the 
variable. To the left appears [0], indicating the first member of an 
array. To the right appears the value of the item being pointed to. 
If the value is a complex data item such as a STRUC or array, 
however, only as much of it as possible is displayed, with the 
values enclosed in braces ({ and }). 


If the pointer is of type BYTE and appears to be pointing toa 
null-terminated character string, more information appears, 
showing the value of each item in the character array. To the left 
in each line appears the array index ([1], [2], and so on), and the 
value appears to the right as it would in a scalar Inspector win- 
dow. In this case, the entire string is also displayed on the top 
line, along with the address of the variable and the address of the 
string that it points to. 


You also get multiple lines if you open the Inspector window with 
a Range local command and specify a count greater than 1. 


Figure 6.14 {=J=Inspecting TextPtr=3=[1] (= 
2ED:0017 QOOA [#test#text] 4 
An assembler pointer OF H"72° (48h) 
Inspector window 


Arrays Array Inspector windows in assembler programs show you the 
value of arrays of data items, such as 


WARRAY DW 10 DUP (0) 
MSG DB "Greetings", 0 
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Figure 6.15 
An assembler array Inspector 
window 


Structures and unions 


Figure 6.16 
An assembler structure 
Inspector window 
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There is a line for each member of the array. To the left on each 
line appears the array index of the item and to the right is its 
present value. If the value is a complex data item such as a 
STRUC, however, only as much of it as possible is displayed. 


You can use the Range local command to examine a portion of an 
array. This is useful if the array has a lot of elements, and you 
want to look at something in the middle of the array. 


{s]=Inspecting Text=3=[t] [4]=y 
72ED:000A a 


Structure Inspector windows in assembler programs show you 
the value of the fields in your STRUC and UNION data objects. For 
example, 


X STRUC 

MEM1 DB 2? 

MEM2 DD ? 

XK ENDS 

ANX X <1, ANX> 

Y UNION 

ASBYTES DB 10 DUP (?) 
ASFLT DT ? 

Y ENDS 

AY Y <?,1.0> 


These Inspector windows have another pane below the one that 
shows the values of the fields. This additional pane shows the 
data type of the field highlighted in the top pane. 


[a]=Inspecting Names=3=[t] [+] 
e72ED:0010 
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' “Whitehall i 
"#" 35 (23h 

"M" 77 (4Dh 


30000 (7530h 


Struc namedata 
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The Inspector window local menu 


Range... 
Change... 


Inspect 

Descend 

New expression... 
Type cast... 


Range... 


Change... 


Inspect 


The commands in this menu give the Inspector window its real 
power. By choosing the Inspect local menu command, for 
example, you create another Inspector window that lets you go 
into your data objects. Other commands in the menu let you 
inspect a range of values and inspect a new variable. 


Press Alt-F10 to pop up the Inspector window local menu. If you 
have control-key shortcuts enabled, press Ctr with the first letter 
of the desired command to access it. 


Sets the starting element and number of elements that you want 
to display. Use this command when you are inspecting an array, 
and you only want to look at a certain subrange of all the 
members of the array. 


If you have a long array and want to look at a few members near 
the middle, use this command to open the Inspector window at 
the array index that you want to examine. 


This command is particularly useful in C where you often declare 
a pointer to a data item—like char *p—but what you really mean 
is that p points to an array of characters, not just a single character. 


Changes the value of the currently highlighted item to the value 
you enter in the dialog box. If the current language permits it, 
Turbo Debugger performs any necessary casting exactly as if the 
appropriate assignment operator had been used to change the 
variable. See Chapter 9 for more information on the assignment 
operator and casting. 


Opens a new Inspector window that shows you the contents of 
the currently highlighted item. This is useful if an item in the 
Inspector window contains more items itself (like a structure or 
array), and you want to see each of those items. 
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Descend 


New Expression... 
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Type Cast... 


If the current Inspector window is inspecting a function, issuing 
the Inspect command shows you the source code for that 
function. 


You can also invoke this command by pressing Enter after high- 
lighting the item you want to inspect. 


You can return to the previous Inspector window by pressing Esc 
to close the new Inspector window. If you are through inspecting 
a data structure and want to remove all the Inspector windows, 
use the Window | Close command or its shortcut, Alt-F3, or click the 
close box with your mouse. 


This command works like the Inspect local menu command 
except that instead of opening a new Inspector window to show 
the contents of the highlighted item, it puts the new item in the 
current Inspector window. This is like a hybrid of the New 
Expression and Inspect commands. 


Once you have descended into a data structure like this, you can’t 
go back to the previous unexpanded data structure. Use this 
command when you want to work your way through a compli- 
cated data structure or long linked list, but you don’t care about 
returning to a previous level of data. This helps reduce the 
number of Inspector windows onscreen. 


Prompts you for a variable name or expression to inspect, without 
creating another Inspector window. This lets you examine other 
data without having to put more Inspector windows on the 
screen. Use this command if you are no longer interested in the 
data in the current Inspector window. 


Inspector windows for Pascal objects and C++ classes are some- 
what different from regular Inspector windows. See Chapter 10 
for a description of object type/class Inspector windows. 


Lets you specify a different data type (Byte, Word, Int, Char 
pointer) for the item being inspected. This is useful if the 
Inspector window contains a symbol for which there is no type 
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information, as well as for explicitly setting the type for untyped 
pointers. 


Chapter 7, Breakpoints 113 


114 


Turbo Debugger User’s Guide 


Chapter 7, Breakpoints 


Breakpoints 


Turbo Debugger uses the single term “breakpoint” to refer to the 
debugger functions usually called breakpoints, watchpoints, and 
tracepoints. 


Traditionally, breakpoints, watchpoints, and tracepoints are 
defined like this: A breakpoint is a place in your program where 
you want execution to stop so that you can examine program 
variables and data structures. A watchpoint causes your program 
to be executed one instruction or source line at a time, watching 
for the value of an expression to become true. A tracepoint causes 
your program to be executed one instruction or source line at a 
time, watching for the value of certain program variables or 
memory-referencing expressions to change. 


Turbo Debugger unifies these three concepts by defining a 
breakpoint in three parts: 


the location in the program where the breakpoint occurs 
8 the condition under which the breakpoint is triggered 
what happens when the breakpoint is triggered 


The location can be at either a single or global location in your 
program (if it is global, the breakpoint can occur at any source line 
or instruction in your program). 


The “condition” can be 


g always 
g when an expression is true 
m when a data object changes value 
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A “pass count” can also be specified, which requires “condition” 
to be true a certain number of times before the breakpoint can be 
triggered. 


The “what happens” can be one of these: 


u stop program execution (a breakpoint) 
log the value of an expression 
m execute an expression (splice code) 


In this chapter, we'll show you how Turbo Debugger breakpoints 
give you more power and flexibility than traditional breakpoints, 
watchpoints, and tracepoints. You'll learn about the Breakpoints 
and Log windows; how to set simple breakpoints, conditional 
breakpoints, and breakpoints that log the value of your program 
variables; and how to set breakpoints that watch for the exact 
moment when a program variable, expression, or data object 
changes value. 


Many times, you just want to set a few simple breakpoints, so that 
if your program reaches any one of these locations, it stops. You 
can set or clear a breakpoint at any location in your program by 
simply placing the cursor on the source code line and pressing F2. 
You can also set a breakpoint on any line of machine code by 
pressing F2 when you are pointing at an instruction in the Code 
pane of a CPU window. Or, if you have a mouse, just click the 
first two columns of the line where you want to set the breakpoint 
(If you’re in the right column, a # appears in the position 
indicator). There is no limit to the number of breakpoints you can 
set. 


The Breakpoints menu 
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You can access the Breakpoints menu at any time by pressing the 
Alt-B hot key. 


Toggle F2 
At es 


coe Alt-F2 
Changed memory global... 
Expression true global... 
Hardware breakpoint... 
Delete all 
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Toggle 


Af... 


Changed 
Memory Global... 


Expression True 
Global... 


Hardware 
Breakpoirt... 


Waming! 


Delete All 
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Sets or clears a breakpoint at the currently highlighted address in 
a Module window or CPU window Code pane. The hot key is F2. 


Lets you set a breakpoint at a specific location in your program. It 
opens a dialog box in which you can set all breakpoint options. 
Alt-F2 is the hot key. 


Sets a breakpoint that’s triggered when an area of memory 
changes value. You are prompted for the area of memory to 
watch. For more information, see the Changed Memory command 
in “The Breakpoints window local menu” section later in this 
chapter. 


Sets a breakpoint that is triggered when the value of an expres- 
sion you supply becomes true. You are prompted for the expres- 
sion. For more information, see the Condition Expression True 
command in “The Breakpoints window local menu” section later 
in this chapter. 


Information on the hardware debugger interface is available in a 
file on your distribution disks. Refer to the README file for how 
to access this disk-based documentation. 


You must have a hardware debugging board in order to use 
hardware debugging. 


Removes all the breakpoints you have set. 
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scope of breakpoint expressions 


Both the action that a breakpoint performs and the condition 
under which it is triggered can be controlled by an expression you 
supply. That expression is evaluated using the scope of the 
address at which the breakpoint is set, not the scope of the current 
location where the program is stopped. This means that your 
breakpoint expression can use only variable names that are valid 
at the address in your program where you set the breakpoint, 
unless you use scope overrides. See Chapter 9 for a complete 
discussion of scopes. 


If you use variables that are local to a routine as part of an expres- 
sion, that breakpoint will execute much more slowly than a break- 
point that uses only global or module local variables. 


The Breakpoints window 


You open a Breakpoints window by choosing the View | 
Breakpoints command. This gives you a way of looking at and 
adjusting the conditions that trigger a breakpoint. You can use 
this window to add new breakpoints, delete breakpoints, and 
adjust existing breakpoints. 


ure 7.) 
Figure Breakpoint © 


Tne Breakpoints window : Always 
IPDEMO.226 Enabled 


Breakpoints windows have two panes. The left pane (Breakpoint 
List) shows a list of all the addresses at which breakpoints are set. 
The right pane (Breakpoint Detail) shows the details of the cur- 
rently highlighted breakpoint in the left pane. Only the break- 
point list pane has a local menu, which you get to by pressing Alt- 
F10. Its options affect whatever breakpoint is highlighted in the 
Breakpoint List pane. 


The Breakpoints 


Window local The commands in this menu let you add new breakpoints, delete 
menu &xisting breakpoints, or change how a breakpoint behaves. 
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Set Options... 


Figure 7.2 
The Breakpoint Options 
dialog box 
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Set options... 
Hardware options... 


Add... 
Remove 


Delete al] 
Inspect 


Alt-F10 pops up the Breakpoints window local menu. If you have 
control-key shortcuts enabled, press Ctr! with the first letter of the 
desired command to access the command directly. 


Opens the Breakpoint Options dialog box, which contains two 
sets of radio buttons, one input box, and one check box. In this 
dialog box, you can 


a define what happens when the breakpoint highlighted in the 
Breakpoints List pane is triggered 
m control the conditions under which the breakpoint is triggered 


f set the number of times an action is encountered before the 
breakpoint triggers 


n enable or disable the breakpoint 
a set or change the breakpoint address 
a make the breakpoint global 


The Action radio buttons have three settings: 


Break Causes your program to stop when the break- 
point is triggered. The Turbo Debugger screen 
reappears, and you can once again enter 
commands to look around at your programs data 
structures. 


Execute Causes an expression to be executed. Enter the 
expression in the Action Expression input box. 
The expression should have some side effect, 
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Log 


such as setting a variable to a value. This option 
can act as a “code splice,” letting you insert an 
expression that will execute before the code in 
your program at the current line number. 


Causes the value of an expression to be recorded 
in the Log window. You are prompted for the 
expression whose value you want to log. Be 
careful that the expression doesn’t have any 
unexpected side effects. See Chapter 9 fora 
description of expressions and side effects. 


The Condition radio buttons have four settings: 


Always 


Changed 
Memory 


Indicates that no additional conditions need be 
true before the breakpoint is triggered. 


Watches a memory variable or object and allows 
the breakpoint to be triggered if the object 
changes. Use the Condition Expression input box 
to enter an expression reproducing the object you 
want to watch, followed by the number of objects 
to watch. The total number of bytes in the 
memory area is the size of the object that the 
expression references times the number of objects. 
For example, if you used C to enter 


(long) a, 4 


the area watched for change would be 16 bytes 
long, since a long is 4 bytes and you said to watch 
four of them. 


If you attach this condition to a global breakpoint, 
your program executes much more slowly 
because the memory area will have to be checked 
for change after every source line has been 
executed. If you've installed a hardware debugger 
device driver, changed memory breakpoints may 
become much faster. If a changed memory break- 
point has hardware assistance, an asterisk (*) 
appears after the breakpoint name in the left 
pane. You can expect then that the breakpoint 
will not slow down your program’s execution. 


By setting this condition on a breakpoint at a 
specific address, you do not incur the speed 
penalty of the global breakpoint, and you can still 
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See disk-based 
documentation about the 
hardware debugger 
interface and the options 
available under this menu. 


Hardware Options... 


Waming! 


Add... 
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check the variable each time a specific line of code 
is executed. 


Expression Allows the breakpoint to be triggered when an 

True expression becomes true (nonzero). Use the 
Condition Expression input box to enter an 
expression to evaluate each time the action is 
encountered. 


Hardware Causes the breakpoint to be triggered by the 
hardware-assisted device driver. Use this menu 
either if you have a 386 system and are using the 
TDH386.SYS device driver, or if you have a 
hardware debugger board installed in your 
system and the board vendor supplies a Turbo 
Debugger device driver. 


The Pass Count input box lets you set the number of times the 
breakpoint action must occur before the breakpoint is triggered. 
The default number is 1. The pass count is decremented only 
when the condition attached to the breakpoint is true. This means 
that if you set a pass count as well as a condition, it causes the 
breakpoint to be triggered the nth time that the condition is true. 


The Breakpoint Disabled check box lets you enable or disable the 
currently highlighted breakpoint. A disabled breakpoint is 
“invisible” until you enable it again; it behaves as if it had been 
deleted. 


This check box is useful if you have defined a complex breakpoint 
that you don’t want to use just now, but will want to use again 
later. It saves you from having to delete the breakpoint, and then 
re-enter it along with its conditions and action. 


Refer to the disk-based documentation about the hardware 
debugger interface for how to use this option. 


You must have a hardware debugging board in order to use 
hardware debugging. 


Opens a dialog box like the Set Options dialog box. You must 
enter an address in the Address input box. 


You can also add a breakpoint by simply starting to type the 
address at which you want to set it. A dialog box appears just as if 
you had invoked the Add command. 
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Remove 


Delete All 


Inspect 


Once you've added the breakpoint, you can use the other local 
menu commands to modify its behavior. When you first add a 
breakpoint, it has a pass count of 1, its condition is set to always 
occur, and the action is to break (stop) your program. 


Removes the currently highlighted breakpoint. 


Removes all breakpoints, both global and those set at specific 
addresses. You will have to set more breakpoints if you want your 
program to stop on a breakpoint. 


Shows you the source code line or assembler instruction that 
corresponds to the currently highlighted breakpoint item. If the 
breakpoint is set at an address that corresponds to a source line in 
your program, a Module window is opened and set to that line. 
Otherwise, a CPU window is opened, with the Code pane set to 
show the instruction at which the breakpoint is set. 


You can also invoke this command by pressing Enter once you 
have the highlight bar positioned over a breakpoint. 


The Log window 
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Figure 7.3 
The Log window 


You create a Log window by choosing the View | Log command. 
This window lets you review a list of significant events that have 
taken place in your debugging session. 


aj=Log 
Breakpoint at TPDEMO.220 
Breakpoint at TPDEMO.220 
Breakpoint at TPDEMO.220 
Breakpoint at TPDEMO.225 
Breakpoint..at’ TPDEMO.226 


le are now entering procedure Params... 


window. If more than 50 lines have been written to the log, the 
oldest lines are lost from the top of the scrolled list. To adjust the 
number of lines, use either a command-line option at startup or 
permanently change the number using the TDINST customization 
program. You can preserve the entire log, continuously writing it 
to a disk file, by using the Open Log File local menu command. 


Here’s a list of what can cause lines to be written to the log: 
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a Your program stops at a location you specified. The location it 
stops at is recorded in the log. 


You issue the Add Comment local menu command. You are 
prompted for a comment to write to the log. 


a A breakpoint is triggered that logs the value of an expression. 
This value is put in the log. 


ps You use the Window! Dump Pane to Log command (from the 
menu bar) to record the current contents of a pane in a window. 


The Log window 


local Menu The commands in this menu let you control writing the log to a 
disk file, stopping and starting logging, adding a comment to the 
Open log file... log, and clearing the log. 


fil 
Loar thos Yes | _Alt-F10 pops up the Log window local menu. If you have control- 


reel es key shortcuts enabled, pressing Cirl and the first letter of the 
desired command accesses the command directly. 


Open Log File... Causes all lines written to the log to be written to a disk file as 
well. A dialog box appears that prompts you for the name of the 
file to write the log to (or you can select a directory and file from 
the list boxes). 


When you open a log file, all the lines already displayed in the log 
window’s scrolling list are written to the disk file. This lets you 
open a disk log file after you see something interesting in the log 
that you want to record to disk. 


If you want to start a disk log that does not start with the lines 
already in the Log window, first choose Erase Log File before 
choosing Open Log File. | 


Close Log File Stops writing lines to the log file specified in the Open Log File 
local menu command, and the file is closed. 


Logging Enables or disables the log, controlling whether anything is 
actually written to the Log window. 
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Add Commert... 


Erase Log 


Lets you insert a comment in the log. You are prompted for a line 
of text that can contain any characters you desire. 


Clears the log list. The Log window will now be blank. This does 
not affect writing the log to a disk file. 


Simple breakpoints 


One of the most common things you'll want to do during debug- 
ging is cause your program to stop if certain pieces of code are 
about to be executed. 


There are a number of ways to set a breakpoint. Each one is 
convenient in different circumstances: 


= Move to the desired source line in a Module window and issue 
the Breakpoints | Toggle command (or press F2 or click the line 
with your mouse). Doing this on a line that already has a break- 
point set causes that breakpoint to be deleted. 


u Move to an instruction in the Code pane of a CPU window and 
issue the Breakpoints | Toggle command (or press F2 or click the 
line with your mouse). Doing this on a line that already has a 
breakpoint set causes that breakpoint to be deleted. 


= Issue the Breakpoints | At command and enter a code address at 
which to set a breakpoint. (A code address has the same format 
as a pointer in the current language. See Chapter 9 about 
expressions.) 


m Issue the Add local menu command from the Breakpoint List 
pane of the Breakpoints window and enter a code address at 
which to set a breakpoint. 


Conditional breakpoints and pass counts 
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There are many occasions where you do not want a breakpoint to 
be triggered every time a certain source statement is executed, 
particularly if that line of code is executed many times before the 
occurrence you are interested in. Turbo Debugger gives you two 
ways to qualify when a breakpoint is actually triggered: pass 
counts and conditions. 
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If you want to stop your program on the tenth call to a function, 
you can set a breakpoint at the start of the function and use the 
Pass Count input box in the Breakpoint Options dialog box to set 
the number of times you want to skip the breakpoint before it is 
actually triggered. 


If you want to stop your program at a specific location but only 
when a certain condition is true, you can specify an expression 
using the Expression True radio button in the Breakpoint Options 
dialog box. Each time the breakpoint is encountered, the expres- 
sion will be evaluated, and if it is true (nonzero), the breakpoint 
will be triggered. This can be used in combination with the pass 
count to trigger a breakpoint only after the expression has been 
true a certain number of times. 


You can use the Changed Memory radio button to specify a 
breakpoint that occurs only after a data item changes value. This 
can be a lot more efficient than specifying a global breakpoint that 
watches for exactly when something changes. If you only watch 
for something to change when a specific source statement is 
reached, it reduces the amount of processing Turbo Debugger 
does in order to detect when the change occurred. 


Global breakpoints 
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If you want to have a breakpoint occur every time a source line or 
instruction is encountered, use global breakpoints. There are a 
number of ways to create a global breakpoint, each best-suited for 
a particular situation: 


g In the Breakpoint Options dialog box, turn on the Global check 
box. Use this method when you want to set a qualifying condi- 
tion or pass count, or when you want to do something other 
than stop when the breakpoint is triggered. 


a Choose the Breakpoints | Changed Memory Global command to 
stop when a specific area of memory changes. 


a Choose the Breakpoints | Expression True Global command to 
stop execution when an expression becomes true. 


When you set a global breakpoint, you usually use the local menu 
in the Breakpoints window to modify the condition or the action; 
otherwise, all you end up with is a breakpoint action that occurs 
on every source line—just like using the Run | Trace Into main 
menu command. 
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If you want to test your global breakpoints each time a source line 
is about to be executed, make sure your current window is not a 
CPU window, then restart your program with one of the Run 
commands from the menu bar (or its function-key equivalents). 


To test your global actions each time a single instruction is 
executed, make sure your current window is a CPU window 
when you restart your program. 


Warning! A global action will occur on every source line or instruction. Use 
a global breakpoint when you want to find out exactly when a 
variable changes or when some condition becomes true. 


Global breakpoints greatly slow the execution of your program. 
However, they can be very convenient for finding where your 
program is “bashing” data. 


> After adding the global breakpoint, you must set a condition that 
will trigger it. 


Breaking for changed data objects 


When you want to find out where in your program a certain data 
object is being changed, first set a global breakpoint using one of 
the techniques outlined in the previous section. Then use the 
Changed Memory radio button in the Breakpoint Options dialog 
box. When the input box appears, enter an expression that refers 
to the memory area you want to keep track of, along with an 
optional count of the number of objects to track. 


Your program will execute slowly when you use this command. 
You may want to localize the problem before using this technique 
to find the exact location where a data item changes. 


If you have installed a hardware device driver, Turbo Debugger 
will try to set a hardware breakpoint to watch for a change in the 
data area. Different hardware debuggers support different 
numbers and types of hardware breakpoints. You can see if a 
breakpoint has used the hardware by opening a Breakpoint 
window with the View! Breakpoints command. Any breakpoint 
that is hardware assisted will have an asterisk (*) beside it. These 
breakpoints will be much faster than global breakpoints that are 
not hardware assisted. 
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Logging variable values 


You can only set one break- 
point per address. 


Sometimes, you may find it useful to log the value of certain 
variables each time you reach a certain place in your program. 
You can log the value of any expression, including, for example, 
the values of the parameters a function is called with. By looking 
at the log each time the function is called, you can determine 
when it was called with erroneous parameters. 


Choose the Log radio button from the Breakpoint Options dialog 
box. You are prompted for the expression whose value is to be 
logged each time the breakpoint is triggered. If you want to log 
the value of multiple variables, you must set multiple break- 
points. 


Executing expressions 
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By executing an expression that has side effects each time a break- 
point is triggered, you can effectively “splice in” new pieces of 
code before a given source line. This is useful when you want to 
alter the behavior of a routine to test a diagnosis or bug fix. This 
saves you from going through the compile-and-link cycle just to 
test a minor change to a routine. 


Of course, this technique is limited to the insertion of an expres- 
sion before an already existing line of code is executed; you can’t 
use this technique to modify existing source lines directly. 


127 


128 Turbo Debugger User's Guide 


Examining and modifying files 


Turbo Debugger treats disk files as a natural extension of the 
program you're debugging. You can examine and modify any file 
on the disk, viewing it either as ASCII text or as hex data. You can 
also make changes to text files using your favorite word processor 
or text editor, all from within Turbo Debugger. 


This chapter shows you how to examine and modify two sorts of 
disk files: those that contain your program source code, and other 
files on disk. 


Examining program source files 


Program source files are your source files that are compiled and 
that generate an object module (an .EXE file). You usually 
examine them when you want to look at the behavior or design of 
a portion of your code. During debugging, you often need to look 
at the source code for a function to verify either that its arguments 
are valid or that it is returning a correct value. 


As you step through your program, Turbo Debugger automati- 
cally displays the source code for the current location in your 
program. 

Files that are included in a source file by a compiler directive and 
generate line #s (like #include in C and INCLUDE in assembler) are 
also considered to be program source files (that is, when you 
choose View | Module, they appear in the Pick a Module list pane). 
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The Module 
Window 


Figure 8.] 
The Module window 


You should always use a Module window to look at your 
program source files because this informs Turbo Debugger that 
the file is a source module. It can then let you do things like 
setting breakpoints or examining program variables simply by 
moving to the appropriate place in your file. These techniques 
and others are described in the following sections. 


You create a Module window by choosing the View | Module 
command from the menu bar (or pressing the hot key, F3). 


[=]=Module: TPDEMO File: TPDEMO.PAS 217——————————-—]=[f] [4] 


=] 
A 
Writeln; 
end; { ParmsOnHeap } 
> begin { program } 
Init; 
Buffer := GetLine; 
while Buffer > '' do 
| 
% 
v 


begin 
ProcessLine(Buf fer); 
Buffer := GetLine; 


end; 
ShowResults; 
ParmsOnHeap; 
end. 


A dialog box appears in which you can enter the name of the 
module you want to view. 


Turbo Debugger will then load the source file for the module that 
you select. It searches for the source file in the following places: 


1. in the directory where the compiler found the .EXE file 

2. in the directories specified by the Options | Path for Source 
command or the —-sd command-line option 

3. in the current directory 

4, in the directory that contains the program you're debugging 


Module windows show the contents of the source file for the 
module you've selected. The title of the Module window shows 
the name of the module you’re viewing, along with the source file 
name and the line number the cursor is on. An arrow (>) in the 
first column of the window shows the current program location 
(CS:IP). 


Note that when you run Turbo Debugger, you'll need both the 
.EXE file and the original source file. Turbo Debugger searches for 


Turbo Debugger User's Guide 


source files first in the directory the compiler found them in when 
it compiled, second in the directory specified in the Options | Path 
for Source command, third in the current directory, and fourth in 
the directory the .EXE file is in. 


If the word modified appears after the file name in the title, the file 
has been changed since it was last compiled or linked to make the 
program you are debugging. This means that the routines in the 
updated source file may no longer have the same line numbers as 
those in the version used to build the program you are debug- 
ging. This can cause the arrow that shows the current program 
location (CS:IP) to be displayed on the wrong line. 


The Module 


window local The Module window local menu provides a number of com- 
mands that let you move around in the displayed module, point 
at data items and examine them, and set the window to display a 


Inspect new file or module. 
Watch 


menu 


You will probably use this menu more than any other menu in 
Turbo Debugger, so you should become quite familiar with its 
various options. 


Use the Alt-F10 key combination to pop up the Module window 
local menu or, if you have control-key shortcuts enabled, use the 
Ctrl key with the first letter of the desired command to access that 
command (for example, Ctrl-S for Search). 


Inspect Opens an Inspector window to show you the contents of the 
program variable at the current cursor position. Before issuing 
this command, you can place the cursor at the program variables 
in the source file that you want to inspect, or you can enter it in 
the input box of the dialog box that appears. 


You can also use the Ins key to select (highlight) an expression to 
inspect. This saves you from typing in an expression that is in 
plain view in the source module. 


Because this command saves you from having to type in each 
name you are interested in, you'll end up using it a lot to examine 
the contents of your program variables. 
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Watch 


Module... 


File... 


Previous 


Line... 


Search... 


Adds the variable at the current cursor position to the Watches 
window. This is useful if you want to monitor the value of a 
variable continuously as your program executes. Before issuing 
this command, you can place the cursor at the program variables 
in the source file that you want to inspect, or you can enter it in 
the input box of the dialog box that appears. 


You can also use the ins key to mark an expression to watch. This 
saves you from typing in an expression that is in plain view in the 
source module. 


Lets you view a different module by picking the one you want 
from the list of modules displayed. This command is useful when 
you are no longer interested in the current module, and you don’t 
want to end up with more Module windows onscreen. 


Lets you switch to view one of the other source files that makes 
up the module you are viewing. Pick the file that you want to 
view from the list of files presented. Most modules only have a 
single source file that contains code. Other files included in a 
module usually only define constants and data structures. Use 
this command if your module has source code in more than one 
file. . 


Use View | File to look at the first file. If you want to see more than 
one, use View | Another | File to open subsequent File windows. 


Returns you to the last source module location you were viewing. 
You can also use this command to return to your previous 
location after you’ve issued a command that changed your 
position in the current module. 


Positions you at a new line number in the file. Enter the new line 
number to go to. If you enter a line number after the last line in 
the file, you will be positioned at the last line in the file. 


Searches for a character string, starting at the current cursor 
position. Enter the string to search for. If the cursor is positioned 
over something that looks like a variable name, the search dialog 
box will come up initialized to that name. Also, if you have 
marked a block in the file using the Ins key, that block will be used 
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to initialize the search dialog box. This saves you from typing if 
what you want to search for is a string that is already in the file 
you are viewing. 


You can search using simple wildcards, with ? indicating a match 
on any single character, and * matching zero or more characters. 
The search does not wrap around from the end of the file to the 
beginning. To search the entire file, go to the first line by pressing 
Cirl-PgUp. 


Next Searches for the next instance of the character string you specified 
with the Search command; you can only use this after issuing a 
Search command. 


Sometimes, a search command matches an unexpected string 
before reaching the one you really wanted to find. Next lets you 
repeat the search without having to reenter what you want to 
search for. 


Origin Positions you at the module and line number that is the current 
program location (CS:IP). If the module you are currently viewing 
is not the module that contains the current program location, the 
Module window will be switched to show that module. This com- 
mand is useful after you have looked around in your code and 
want to return to where your program is currently stopped. 


Goto... Positions you at any location within your program. Enter the 
address you want to examine; you can enter a line number, a 
function name, or a hex address. See Chapter 9 for a complete 
description of the ways to enter an address. 


You can also invoke this command by simply starting to type the 
label to go to. This brings up a dialog box exactly as if you had 
specified the Run | Execute To command. This is a handy hot key 
for this frequently used command. 


Edit Starts up your choice of an editor so that you can make changes to 
the source file for the module you are viewing. You can specify 
the command that starts your editor from the installation 
program TDINST. 
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Examining other disk files 


The File window 


Figure 8.2 
The File window 


Figure 8.3 


The File window showing hex 
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data 


The File window 
local menu 


You can examine or modify any file on your system by using a 
File window. You can view the file either as ASCII text or as hex 
data bytes, using the Display As command described in a later 
section of this chapter. 


You create a File window by choosing the View | File command 
from the menu bar. You can use DOS-style wildcards to get a list 


of file choices, or you can type a specific file name to load. 
teens 9: snetts Tes \debas \pnearas\tenes=(14 Wi 
le <tcdemo.c> 


i 


a 
* Demonstration program to show off Turb 
* Reads words from standard input, analyz 
* 


yincluge aL h> v 
Lt. wean OPPS eR NO Pe, OL Pe PL oe 


File windows show the contents of the file you’ve selected. The 
name of the file you are viewing is displayed at the top of the 
window, along with the line number the cursor is on if the file is 
displayed as ASCII text. 


When you first create a File window, the file will appear either as 
ASCII text or as hexadecimal bytes, depending on whether the file 
contains what Turbo Debugger thinks is ASCII text or binary 
data. You can switch between ASCII and hex display at any time 
using the Display As local menu command described later. 


ri bat g: rvnettt eee ote Wa 
00008: 3c ra 63 64 65 6d 6f 2e <tcdemo. "i 
00010: 63 3e Od Oa 20 2a Od Oa c>s§ «d§f 
00018: 20 2a 09 44 65 6d 6f 6e oDemon 
00020: 73 74 72 61 74 69 6f be stration 
00028: 20 70 72 6f 67 i 61 6d = program 
00030: Zo th ot aH 73 68 of UU i Le v 


The File window local menu has a number of commands for 
moving around in a disk file, changing the way the contents of the 
file are displayed, and making changes to the file. 
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Goto 
Search 
Next 


Display as Ascii 
File... 
Edit 


Use the Alt-F10 key combination to pop up the File window local 
menu or, if you have control-key shortcuts enabled, use the Ctrl 
key with the first letter of the desired command to access it. 


Goto Positions you at a new line number or offset in the file. If you are 
viewing the file as ASCII text, enter the new line number to go to. 
If you are viewing the file as hexadecimal bytes, enter the offset 
from the start of the file at which to start displaying. You can use 
the full expression parser for entering the offset. If you enter a line 
number after the last line in the file or an offset beyond the end of 
the file, you will be positioned at the end of the file. 


search Searches fora character string, starting at the current cursor 
position. You are prompted to enter the string to search for. If the 
cursor is positioned on something that looks like a symbol name, 
the Search dialog box comes up initialized to that name. Also, if 
you have marked a block in the file using the Ins key, that block 
will be used to initialize the Search dialog box. This saves you 
from typing if what you want to search for is a string that is 
already in the file you are viewing. The format of the search string 
depends on whether the file is displayed in ASCII or hex. 


If the file is displayed in ASCII, you can use simple wildcards, 
with ? indicating a match on any single character, and * matching 
0 or more characters. 


See Chapter 9 forcomplete If the file is displayed in hexadecimal bytes, enter a byte list 

information about bytelists. consisting of a series of byte values or quoted character strings, 
using the syntax of whatever language you are using for 
expressions. 


The search does not wrap around from the end of the file to the 
beginning. To search the entire file, go to the first line of the file by 
pressing Ctrl-PgUp. 


You can also invoke this command by simply starting to type the 
string that you want to search for. This brings up a dialog box 
exactly as if you had specified the Search command. 
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Next Searches for the next instance of the character string you specified 
with the Search command; you can only use this command after 
first issuing a Search command. 


This is useful when your Search command didn’t find the 
instance of the string you wanted. You can keep issuing this 
command until you find what you want. 


Display As_ Toggles between displaying the file as ASCII text or hexadecimal 
bytes. When you select ASCII display, the file appears as you are 
used to seeing it on the screen in an editor or word processor. If 
you select Hex display, each line starts with the hex offset from the 
beginning of the file for the bytes on the line. Eight bytes of data 
are displayed ona line. To the right of the hex display of the 
bytes, the display character for each byte appears. The full display 
character set can be displayed, so byte values less than 32 or 
greater than 127 appear as the corresponding display symbol. 


File... Lets you switch to a different file. You can use DOS-style 
wildcards to get a list of file choices, or you can type a specific file 
name to load. This lets you view a different file without putting a 
new File window onscreen. If you want to view two different files 
or two parts of the same file simultaneously, issue the View | 
Another | File command to make another File window. 


Edit Ifyou are viewing the file as ASCII text, this command lets you 
make changes to the file you are viewing by invoking the editor 
you specified with the TDINST installation program. 


Chapter 9hasacomplete If you are viewing the file as hex data bytes, the debugger does 
description of byte lists. not start your editor. Instead, you are prompted for the bytes to 
replace those at the current cursor position. Enter a byte list, just 
as if you were entering a list of bytes to search for. 
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Each language evaluates an 
expression differently. 
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Expressions 


Expressions can be a mixture of symbols from your program (that 
is, variables and names of routines), and constants and operators 
from one of the supported languages: C, Pascal, or assembler. 


Turbo Debugger can evaluate expressions and tell you their value. 
You can also use expressions to indicate a data item in memory 
whose value you want to know. You can supply an expression in 
any dialog box that asks for a value or an address in memory. 


Use Data | Evaluate/Modify to open the Evaluate/ Modify dialog 
box, which tells you the value of an expression. (You can also use 
this dialog box as a simple calculator.) | 


In this chapter, you'll learn how Turbo Debugger chooses which 
language to use for evaluating an expression, and how you can 
make it use a specific language. We describe the components of 
expressions that are common to all the languages, such as source- 
line numbers and access to the processor registers. We then 
describe the components that can make up an expression in each 
language, including constants, program variables, strings, and 
operators. For each language, we also list the operators that Turbo 
Debugger supports and the syntax of expressions. 


For a complete discussion of C, Pascal, and assembler expressions, 
refer to your Turbo C Getting Started and Programmer's Guide, the 
Turbo Pascal User’s Guide and Reference Guide, or the Turbo 
Assembler Reference Guide. 
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Choosing the language for expression evaluation 
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Turbo Debugger normally determines which expression evaluator 
and language to use from the language of the current module. 
This is the module in which your program is stopped. You can 
override this by using the Options | Language command to open 
the Expression Language dialog box; in it you can set radio 
buttons to Source, C, Pascal, or Assembler. If you choose Source, 
expressions are evaluated in the manner of the module’s 
language. (If Turbo Debugger can’t determine the module's 
language, it uses the expression rules for Turbo Assembler.) 


Usually, you let Turbo Debugger choose which language to use. 
Sometimes, however, you'll find it useful to set the language 
explicitly; for example, when you are debugging an assembler 
module that is called from one of the other languages. By expli- 
citly setting expression evaluation to use a particular language, 
you can access your data in the way you refer to it with that 
language, even though your current module uses a different 
language. 

Sometimes it is convenient to treat expressions or variables as if 
they had been written in a different language; for example, if you 
are debugging a Pascal program, assembly language or C conven- 
tions may offer an easier way to change the value of a byte stored 
in a string. 


So long as your initial choice of language is correct when you 
enter Turbo Debugger, you should have no difficulty using other 
language conventions. Turbo Debugger still retains information 
about the original source language and will handle the conver- 
sions and data storage appropriately. If the language seems ambi- 
guous, Turbo Debugger defaults to assembly language. 


Even if you deliberately choose the wrong language when you 
enter Turbo Debugger, it will still be able to get some information 
about the original source language from the symbol table and the 
Original source file. Under some circumstances, however, it may 
be possible to confuse Turbo Debugger into storing data 
incorrectly. 
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Code addresses, data addresses, and line numbers 


Normally, when you want to access a variable or the name of a 
routine in your program, you simply type its name. However, you 
can also type an expression that evalutes to a memory pointer, or 
specify code addresses as source line numbers by preceding the 
line number with a pound sign (#), like #123. The next section 
describes how to access symbols outside the current scope. 


Of course, you can also specify a regular segment:offset address, 
using the hexadecimal syntax for the source code language of 
your program: 


Language Format Example 

Cc Oxnnnn 0x1234:0x0010 

Pascal $Snnnn $1234:$0010 

assembler nnnnh 1234h:0010h 
1234h:0B234h 


In assembler, hex numbers starting with A to F must be prefixed with a zero. 


Accessing symbols outside the current scope 
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Where the debugger looks for a symbol is known as the scope of 
that symbol. Accessing symbols outside of the current scope is an 
advanced concept that you don’t really need to understand in 
order to use Turbo Debugger in most situations. 


Normally, Turbo Debugger looks for a symbol in an expression 
the same way a compiler would. For example, C first looks in the 
current function, then in the current module for a static (local) 
symbol, then for a global symbol. Pascal first looks in the current 
procedure or function, then in an “outer” subprogram (if the 
active scope is nested inside another), then in the implementation 
section of the current unit (if the current scope resides in a unit), 
and then for a global symbol. 


If Turbo Debugger doesn’t find a symbol using these techniques, 
it searches through all the other modules to find a static symbol 
that matches. This lets you reference identifiers in other modules 
without having to explicitly mention the module name. 


If you want to force Turbo Debugger to look elsewhere for a 
symbol, you can exert total control over where to look for a 
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symbol name by specifying a module, a file within a module, or a 
routine to look inside. You can access any symbol in your pro- 
gram that has a defined value, even symbols that are private to a 
function or procedure and have names that conflict with other 
symbols. 


Scope override 


syntax No matter what language you’re using, you use the same method 
to override the scope of a symbol name. 


Normally, you use a pound sign (#) to separate the components of 
the scope. If it’s not ambiguous in the current language, you can 
also use a period (.) instead of # and omit the initial pound sign. 


The following syntax describes scope overriding; brackets ([]) 
indicate optional items: 


(#module[# filename] ] #linenumber|[#variablename] 
or 
[#module[# filename] ] [#functionname] #variablename 


If you don’t specify a module, the current module is assumed. 
Here are some examples of valid symbol expressions with scope 
overrides. There is one example for each of the legal combinations 
of elements that you can use to override a scope. 


The first six examples show various ways of using line numbers 
to generate addresses and override scopes: 


#123 Line 123 in the current module 

#123#myvarl Symbol myvar1 accessible from line 
123 of the current module 

fmymodule#123 Line 123 in module mymodule 

fmymodule#1234#myvarl Symbol myvar1 accessible from line 
123 in module mymodule 

#mymodule#filel#123 Line 123 in source file filel, which is 
part of module mymodule 


fmymoduleffilel#123#myvarl | Symbol myvarl accessible from line 
123 in source file filel, which is part 
of mymodule 


The next six examples show various ways of overriding the scope 
of a variable by using a module, file, or function name: 
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#myvar2 


#my func#myvar2 


#mymodule#myvar2 


§mymodulefmy func#myvar2 


#mymodule#file2#myvar2 


#mymodule#file2#myfunc 
#myvar2 


Same as myvar2 without the # 


Variable myvar2 accessible from 
routine myfunc 


Variable myvar2 accessible from 
module mymodule 


Variable myvar2 accessible from 
routine myfunc in module mymodule 


Variable myvar2 accessible from 
file2, which is included in mymodule 


Variable myvar2 accessible from 
myfunc defined in file file2, which is 
included in mymodule 


Turbo Debugger also supports Pascal’s unit-override syntax: 


unitname.symbolname 


Finally, Turbo Debugger lets you override scope by using object, 
class, method, and member function names. Here’s some 


examples: 


AnInstance 


AnInstance.AField 


AnObjectType.AMethod 


AnInstance.AMethod 


AUnit.AnInstance.AField 


AUnit .AnObjectType.AMethod 
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Instance AnInstance accessible in the 
current scope. 


Field AField accessible in instance 
AnInstance accessible in the current 
scope 

Method AMethod accessible in object 
type AnObjectType accessible in the 
current scope 


Method AMethod accessible in 
instance AnInstance accessible in the 
current scope 


Field AMethod accessible in instance 
AntInstance accessible in unit AUnit 


Method AMethod accessible in object 
type AnObjectType accessible in unit 
Aunit 
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AUnit .AnObjectType.AMethod. Local variable AVar accessible in 

ANestedProc.AVar procedure ANestedProc accessible in 
method AMethod accessible in object 
type AnObjectType accessible in unit 
Aunit 


You can enter such qualified identifier expressions anywhere an 
expression is valid, including in the Evaluate/Modify dialog box 
and the Watches window, or when you're changing an expression 
in an Inspector window or using the local menu in the Module 
window to Goto a method, member function, or procedure 
address in the source code. 


Cc Ifyou are debugging a C++ program and want to examine a 
function with an overloaded name, just enter the name of the 
function in the appropriate input box. Turbo Debugger opens the 
Pick a Symbol Name dialog box with a list box of all the functions 
of that name, with their arguments, so you can choose the one 
you want. 


Implied scope for 


@xpression Whenever Turbo Debugger evaluates an expression, it must 

evaluation decide where in your program the “current scope” is that is used 
for any symbol names without an explicit scope override. Deter- 
mining scope is important because in many languages you can 
have symbols inside functions or procedures with the same name 
as global symbols; Turbo Debugger must know which instance of 
a symbol you mean. 


Turbo Debugger usually uses the current cursor position as the 
context for “deciding” about scope. Thus, you can set the scope 
where an expression will be evaluated by moving the cursor toa 
specific line in a Module window. 


This means that if you have moved the cursor off the current line 
where your program is stopped, you may get unexpected results 
from evaluating expressions. If you want to be sure that expres- 
sions are evaluated in your programs current scope, use the 
Origin local menu command in the Module window to return to 
the current location in the source code. You can also set the 
expression scope by moving around inside the Code pane of a 
CPU window, by cursoring to a routine in the Stack window, or 
by cursoring to a routine name in a Variables window. 
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Byte lists 


C expressions 


Several commands ask you to enter a list of bytes, including the 
Search and Change local menu commands in the Data pane of the 
CPU window, and the Search and Change local menu commands 
of the File window when it’s displaying a file in hexadecimal 
format. 


A byte list can be any mixture of scalar (non-floating-point) num- 
bers and strings in the syntax of the current language, determined 
by the Options | Language command. Both strings and scalars use 
the same syntax as expressions. Scalars are converted into a 
corresponding byte sequence. For example, a Pascal Longint 
value of 123456 becomes a 4-byte hex quantity 40 E2 01 00. 


Language Byte list Hex data 

Cc “ab” 0x04 “c” 61 62 04 63 
Pascal ‘ab’#4’c’ 61 62 04 63 
Assembler 1234 “AB” 34 12 41 42 


C symbols 
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Turbo Debugger supports the complete C expression syntax. A C 
expression consists of a mixture of symbols, operators, strings, 
variables, and constants. Each of these components is described in 
one of the following sections. 


A symbol is the name of a data object or routine in your program. 
A symbol name starts with a letter (a-z, A-Z) or underscore (_). 
Subsequent characters in the symbol may contain these characters 
and also the digits 0 through 9. You can omit the beginning 
underscore from symbol names; if you enter a symbol name 
without an underscore and that name cannot be found, it is 
searched for again with an underscore at the beginning. The 
compiler automatically puts an underscore at the start of your 
symbol names, which saves you from having to remember to add 
it. 
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C register 


pseudovariables Turbo Debugger lets you access the processor registers using the 
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Pseudovariable 


Type 


unsigned int 
unsigned char 
unsigned char 


unsigned int 
unsigned char 
unsigned char 


unsigned int 
unsigned char 
unsigned char 


unsigned int 
unsigned char 
unsigned char 


unsigned int 

unsigned char 
unsigned char 
unsigned char 


unsigned int 
unsigned char 
unsigned char 
unsigned char 
unsigned int 


same technique as the Turbo C compiler, namely pseudovariables. 
A pseudovariable is a variable name that corresponds to a given 
processor register. 


Register 
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C constants and 
number formats 


Escape 
sequences 
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The following pseudovariables let you access the 80386 processor 
registers: 


Pseudovariable Type Register 
_EAX unsigned long EAX 
_EBX unsigned long EBX 
_ECX unsigned long ECX 
_EDX unsigned long EDX 
_ESP unsigned long ESP 
_EBP unsigned long EBP 
_EDI unsigned long EDI 
_ESI unsigned long ESI 
_FS unsigned int FS 
_GS unsigned int GS 


Constants can be either floating point or integer. 


An integer constant is specified in decimal, unless one of the C 
conventions for overriding this is used: 


Format Radix 

digits decimal 
Odigits octal 
OXdigits hexadecimal 
Oxdigits hexadecimal 


Constants are normally of type int (16 bits). If you want to define a 
long (32-bit) constant, you must add an / or L at the end of the 
number. For example, 123456L. 


A floating-point constant contains a decimal point and can use 
decimal or scientific notation. For example, 


1.234 4.5et11 


A string is a sequence of characters enclosed in double quotes (""). 


You can use the standard C backslash (\) as an escape character. 
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Sequence Value Character 


\\ 0X5C Backslash 

\a 0X07 Bell 

\b 0X08 Backspace 

\f 0x0C Formfeed 

\n OX0A Newline 

\r 0X0D Carriage return 
\t 0X09 Horizontal tab 
\v OX0B Vertical tab 
\xnn nn Hex byte value 
\nnn nnn Octal byte value 


If you follow the backslash with any other character than those 
listed here, that character is inserted into the string unchanged. 


C operators 
precedence _ Turbo Debugger uses the same operators as C, with the same 

precedence. The debugger has one operator that is part of the C++ 
set of operators: the double colon (::). This operator has a higher 
priority than any of the regular C operators. It is used to make a 
constant far address out of the expression that precedes it and the 
expression that follows it; for example, 

0X1234: :0X1000 

_ES::_BX 
The primary expression operators 

I] . -— sizeof 
have the highest priority, from left to right. The unary operators 

* & - $! ~ +4 - 
are of a lower priority than the primary operators but a greater 
priority than the binary operators, grouped from right to left. The 


priority of the binary operators, in descending order, is as follows 
(operators on the same line have the same priority): 
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Executing C 
functions in your 
program 
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highest * / % 


lowest 


The single ternary operator, ?:, has a priority below that of the 
binary operators. 


The assignment operators are below the ternary operator in 
priority. They are all of equal priority, and group from right to 
left: 


=. Se + /= = >>= .<<= = A= j= 


You can call functions from a C expression exactly as you do in 
your source code. Turbo Debugger actually executes your pro- 
gram code with the function arguments that you supply. This can 
be a very useful way of quickly testing the behavior of a function 
you've written. You can repeatedly call it with different argu- 
ments and then check that the returned value is correct each time. 


The following function raises one integer number to a power (x4): 


long power{int x, int y) 
{ 
long temp = 1; 
while (y--) 
temp *= x; 
return (temp) ; 


} 


The following table shows the result of calls to this function with 
different function arguments: 


C expression Result 

power(3,2) * 2 18 

25 + power(5,8) 390650 

power(2) Error (missing argument) 
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C expressions with 


C reserved words 
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side effects 


and type 
conversion 


A side effect occurs when you evaluate a C expression that 
changes the value of a data item in the process of being evaluated. 
In some cases, you may want a side effect, using it to intentionally 
modify the value of a program variable. At other times, you want 
to be careful to avoid them, so it’s important to understand when 
a side effect can occur. 


The assignment operators (=, +=, and so on) change the value of 
the data item on the left side of the operator. The increment and 
decrement (++ and ——) operators change the value of the data 
item that they precede or follow, depending on whether they are 
used as prefix or postfix operators. 


A more subtle type of side effect can occur if you execute a func- 
tion that’s part of your program. For example, if you evaluate the 
C expression 


myfunc(1,2,3) + 7 


your program may misbehave later if myfune changed the value 
of other variables in your program. 


Turbo Debugger lets you perform type conversions on (cast) 
pointers exactly as you would do ina C program. A type conver- — 
sion consists of a C data-type declaration between parentheses. It 
must come before an expression that evaluates to a memory 
pointer. 


Type conversions are useful if you want to examine the contents 
of a memory location pointed to by a far address you generated 
using the double colon (::) operator, for example, 


(long far *)0x3456::0 
(char far *) ES:: BX 


You can use a type conversion to access a program variable for 
which there is no type information, which happens when you 
compile a module without generating debugging-type informa- 
tion. Rather than recompiling and relinking, if you know the data 
type of a variable, you can simply put that in a type conversion 
before the name of the variable. 
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For example, if your variable iptr is a pointer to an integer, you 
can examine the integer that it points to by evaluating the C 
expression 

*(int *)iptr 
You can also use the Type Cast command in the Inspector 
window local menu for this purpose. 


Use the following C reserved words to perform type conversions 
for Turbo Debugger: 


char huge struct 
double int union 
enum long unsigned 
far near 

float short 


Pascal expressions 


Pascal symbols 


Pascal constants 
and number 
formats 
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Turbo Debugger supports the Pascal expression syntax, with the 
exception of string concatenation and set operators. A Pascal 
expression consists of a mixture of symbols, operators, strings, 
variables, and constants. The following sections describe each of 
the components that make up an expression. 


Symbols in Pascal are user-defined names for data items or rou- 
tines in your program. A Pascal symbol name can start witha 
letter (a-z, A-Z) or an underscore (_). Subsequent characters in the 
name can contain the digits (0 to 9) and the underscore, as well as 
letters. 


Normally, a symbol obeys the Pascal scoping rules, with “nested” 
local symbols overriding other symbols of the same name. You 
can override this scoping if you want to access symbols in other 
scopes. For more details, see the section “Accessing symbols 
outside the current scope” on page 139. 


Constants can be either real (floating-point) or integer constants. 
Negative constants start with a minus sign (-). If the number con- 
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tains a decimal point or an e that introduces an exponent, it is a 
real number; for example, 


123.4 456e34 123.45e-5 


Integer-type constants are normally decimal, unless they start 
with a dollar sign ($) to indicate hexadecimal. Decimal integer 
constants must be between —2,137,483,648 and 2,147,483,647. 
Hexadecimal constants must be between $00000000 and 
$FFFFFFFF. 


Pascal strings 


A string is simply a group of characters surrounded by single 
quotes; for example: 


‘abc! 


You can embed control characters in a string by preceding the 
decimal control character value with a #. For example, 


"def! #7’ xyz! 


Pascal operators 
and operator Turbo Debugger supports all the Pascal expression operators. 


Precedence The unary operators are of the highest precedence and are of 


equal priority. 
@ Takes address of an identifier 
. Contents of pointer 
not Bitwise complement 
typeid § Typecast 
+ Unary plus, positive 


= Unary minus, negative 


The binary operators are of a lower precedence than the unary 
operators. They are listed here in descending order (operators on 
the same line have the same priority): 


* / div mod and_=e shl_ shr 
in + — or. xor 
< <= > o= = <> 


The assignment operator (:=) has the lowest precedence; it returns 
a value, as in C. 
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Calling Pascal 
functions and 


You can reference Pascal functions and procedures in expressions. 


procedures For example, assume you have declared a function called 


HalfFunc that divides an integer by 2: 
function HalfFunc(i:Integer) Real; 


You can then choose the Data | Evaluate/Modify command and 
call HalfFunc as follows: 


HalfFunc (3) 
HalfFunc(10) = HalfFunc(10 div 2) 


You can also call procedures, although not in an expression, of 
course. When you enter a procedure or function name by itself, 
Turbo Debugger reports its address and declaration. To call a 
function or procedure that has no parameter, place a set of empty 
parentheses after the symbol name. For example, 


MyProc () Calls MyProc 

MyProc Reports MyProc’s address, and so on 

MyFunc = 5 Compares address of MyFunc to 5 

MyFunc() = 5Calls MyFunc and compares returned value to 5 


Assembler expressions 


Assembler 
symbols 
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Turbo Debugger supports the complete assembler expression 
syntax. An assembler expression consists of a mixture of symbols, 
operators, strings, variables, and constants. Each of these compo- 
nents is described in this section. 


Symbols are user-defined names for data items and routines in 
your program. An assembler symbol name starts with a letter (a-z, 
A-Z) or one of these symbols: @ ? _ $. Subsequent characters in 
the symbol can contain the digits 0 to 9, as well as these 
characters. The period (.) can also be used as the first character of 
a symbol name, but not within the name. 


The special symbol $ refers to your current program location as 
indicated by the CS:IP register pair. 
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Assembler 
constants 


Assembler 
Operators 


Constants can be either floating point or integer. A floating-point 
constant contains a decimal point and may use decimal or scien- 
tific notation. For example, 


1.234 4.5et1l 


Integer constants are hexadecimal unless you use one of the 
assembler conventions for overriding the radix: 


Format Radix 
digitsH Hexadecimal 
digitsO Octal 
digitsQ Octal 

digitsD Decimal 
digitsB Binary 


You must always start a hexadecimal number with one of the 
digits 0 to 9. If you want to enter a number that starts with one of 
the letters A to F, you must first precede it with a 0 (zero). 


Turbo Debugger supports most of the assembler operators, listed 
here in order of priority: 


xxx PTR (BYTE PTR...) 
. (structure member selector) 
: (segment override) 
OR XOR 

AND 

NOT 

EQ NE LT LE GT GE 
+ a, 

* / MOD SHR SHL 
Unary + Unary - 
OFFSET SEG 

Q [] 


Variables can be changed using the = assignment operator. For 
example, 


a = [BYTE PTR DS:4] 
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Format control 


When you supply an expression to be displayed, Turbo Debugger 
displays it in a format based on the type of data it is. Turbo 
Debugger ignores a format control that is wrong for a particular 


data type. 


If you want to change the default display format for an expres- 
sion, place a comma at the end of the expression and supply an 
optional repeat count followed by an optional format letter. You 
can only supply a repeat count for pointers or arrays. 


Character 


Cc 


f[#] 


md 


xorh 
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Format 


Displays a character or string expression as raw 
characters. Normally, nonprinting character values are 
displayed as some type of escape or numeric format. 
This option forces the characters to be displayed using 
the full IBM display character set. 


Displays an integer as a decimal number. 


Displays as floating-point format with the specified 
number of digits. If you don’t supply a number of 
digits, as many as necessary are used. 


Displays a memory-referencing expression as hex 
bytes. 


Displays a memory-referencing expression as decimal 
bytes. 


Displays a raw pointer value, showing segment as a 
register name if applicable. Also shows the object 
pointed to. This is the default if no format control is 
specified. 


Displays an array or a pointer to an array of characters 
as a quoted character string. The string is terminated 
with a null character. 


Displays an integer as a hexadecimal number. 
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C++ and object-oriented Pascal 
debugging 


To meet the needs of the C++ and object-oriented Pascal 
revolution, Turbo Debugger has been enhanced to support 
object-oriented programming. To use these new features, you 
must have version 5.5 of Turbo Pascal or Turbo C++, and version 
2.0 of Turbo Debugger. 


Besides extensions that let you trace into object methods or class 
member functions and examine objects or classes in the Evaluate/ 
Modify dialog box and the Watches window, Turbo Debugger 2.0 
comes equipped with a special set of windows and local menus 
specifically designed for objects and classes. 


The Hierarchy window 


Turbo Debugger provides a special window for examining object 
or class hierarchies. You can bring up the Hierarchy window by 
choosing View | Hierarchy. 
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Figure 10.1] 
The Hierarchy window 


Use Tab fo move between 
the two panes. 


The Object Type 
List pane 


The Object Type/Class 
List pane local menu 


Inspect 
Tree 
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The Hierarchy window displays information on object or class 
types rather than instances. The left pane lists in alphabetical order 
the types used by the module being debugged. The right pane 
(two panes if you are running a C++ program with multiple 
inheritance) shows all objects or classes in their hierarchies, using 
a line graphic that places the base type at the left margin of the 
pane and displays descendants (also ancestors for classes with 
multiple inheritance) beneath and to the right of the base type, 
with lines indicating ancestor and descendant relationships. 


The left pane provides an alphabetical list of all object or class 
types used by the current module. It supports an incremental 
matching feature to eliminate the need to cursor through large 
lists of types: When the highlight bar is in the left pane, simply 
start typing the name of the object or class type you're looking for. 
At each keypress, Turbo Debugger highlights the first type 
matching all keys pressed up to that point. 


Press Enter to open an object type/class Inspector window for the 
highlighted type. Object type/class Inspector windows are 
described on page 158. 


Press Alt-F10 to display the local menu for the pane. You can use 
the control-key shortcuts if you’ve enabled hot keys with TDINST. 
This local menu contains two items: Inspect and Tree. 


inspect 


Displays an object type/class Inspector window for the 
highlighted type. 
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Tree 


Moves to the right pane of the window, in which the hierarchy 
tree is displayed, and places the highlight bar on the type that was 
highlighted in the left pane. 


The Hierarchy 


Tree pane The right pane displays the hierarchy tree for all objects or classes 
used by the current module. Ancestor and descendant relation- 
ships are indicated by lines, with descendants to the right of and 
below their ancestors. 


To locate a single object or class type in a complex hierarchy tree, 
go back to the left pane and use the incremental search feature; 
then choose the Tree item from the local menu to move back into 
the hierarchy tree. The matched type appears under the highlight 
bar. 


When you press Enter, an object type/class Inspector window 
appears for the highlighted type. 


CL Ifyou have loaded a C++ program that uses classes with multiple 
inheritance, a third pane, the Parent Tree pane, appears below the 
Hierarchy Tree pane in the Hierarchy window. If the class you are 
examining has multiple ancestors, and if the Parent command in 
the Hierarchy Tree pane local menu is set to Yes, a reverse tree 
appears in the Parent Tree pane with the message Parents of 
Class at the left margin of the pane and the ancestors displayed 
beneath and to the right, with lines indicating descendant and an- 
cestor relationships. 


You can open an object type/class Inspector window for any class 
that appears in the Parent Tree pane, just as you can in the 
Hierarchy Tree pane. 


The Hierarchy Tree The Hierarchy Tree pane local menu (Al-F10 in the right pane) has 
pane local menu(s) _ only one item: Inspect. When you choose it, an object type/class 
Inspector window appears for the highlighted type. However, a 


faster and easier method is simply to press Enter when you want 


to inspect the highlighted type. 
If you have loaded a C++ program that uses classes with multiple 
Parents Yes 


inheritance, the Hierarchy Tree pane local menu contains a 
second command, Parents. This is a toggle with which you can 
control whether to show the ancestors of a class in the Parent Tree 
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The Parent Tree pane 


local menu 


pane. This is useful if a class you are examining has multiple 
inheritance. The default for Parents is Yes. 


Finally, the Parent Tree pane, if it exists, has a local menu of its 
own, with a single command, Inspect. It works just the same as 
the Inspect command in the Hierarchy Tree pane local menu: It 
opens an Inspector window for the highlighted object type or 
class. 


Object type/class Inspector windows 
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Figure 10.2 
An object type/class 
Inspector window 


Turbo Debugger provides a special type of Inspector window to 
let you inspect the details of an object type: the object type/class 
Inspector window. The window summarizes type information, 
but does not reference any particular instance. 


[a]=Class LinearGauge=4=[1] [1] 
int_Range::Low A 


:sGetHigh() 


The window is divided horizontally into two panes, with the top 
pane listing the data fields or members of the type and the bottom 
pane listing the method or member function names and (if the 
selected item is a function rather than a procedure) the function 
return type. Use the Tab key to move between the two panes of 
the object type/class Inspector window. 


If the highlighted data field is an object or class type, or a pointer 
to an object or class type, pressing Enter opens another object 
type/class Inspector window for the highlighted type. (This 
action is identical to selecting the Inspect command in the local 
menu for this pane.) In this way, complex nested structures of 
objects or classes can be inspected quickly with a minimum of 
keystrokes. 


For brevity’s sake, method or member function parameters are not 
shown in the object type/class Inspector window. To examine 
parameters, highlight the method or member function and press 
Enter. A method/member function Inspector window appears. 
The top pane of the window displays the code address for the 
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The object type/ 
class Inspector 
window local 
menus 


Inspect 


Hierarchy 


Show Inherited 


Inspect 
Hierarchy 
Show inherited Yes 


object or class type’s implementation of the selected method or 
member function, and the names and types of all its parameters. If 
your source program is in object-oriented Pascal, the bottom pane 
of the window indicates whether the method is a procedure or a 
function. 


Pressing Enter from anywhere within the method/member func- 
tion Inspector window brings the Module window to the fore- 
ground, with the cursor at the code that implements the method 
or member function being inspected. 


As with standard inspectors, Esc closes the current Inspector 
window and Alt-F3 closes them all. 


Pressing Alt-F10 brings up the local menu for either pane. If 
control-key shortcuts are enabled (through TDINST), you can get 
to a local menu item by pressing Ctrl and the first letter of the item. 


Inspect 
Hierarchy 
Show inherited Yes 


The Object Data Field pane local menu contains these items: 


If the highlighted field is an object or class type or a pointer to 
one, a new object type/class Inspector window is opened for the 
highlighted field. 


Opens an Hierarchy window for the object or class type being 
inspected. The Hierarchy window is described on page 155. 


Yes is the default value of this toggle. When it is set to Yes, all data 
fields or members are shown, whether they are defined within the 
type of the inspected object or class or inherited from an ancestor 
type. When it is set to No, only those fields/ members defined 
within the type being inspected are displayed. 


The local menu commands for the bottom Object Method pane 
are Inspect, Hierarchy, and Show Inherited. 
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Inspect 


Hierarchy 


Show Inherited 


A method /member function Inspector window is opened for the 
highlighted item. If you press Ctr- when the cursor is positioned 
over the address shown in the method/member function 
Inspector window, the Module window is brought to the fore- 
ground with the cursor at the code that implements what is being 
inspected. 


Opens an Hierarchy window for the object or class type being 
inspected. The Hierarchy window is described on page 155. 


Yes is the default value of this toggle. When it is set to Yes, all 
methods or member functions are shown, whether they are 
defined within the type being inspected or inherited from an 
ancestor. When it is set to No, only those methods or member 
functions are displayed that are defined within the object type 
being inspected. 


Object instance Inspector windows 
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Figure 10.3 
An object/class instance 
Inspector window 


Object type/class Inspector windows provide information about 
object or class types, but say nothing about the data contained ina 
particular object or class instance at a particular time during pro- 
gram execution. Turbo Debugger provides an extended form of 
the familiar record Inspector window specifically to inspect object 
and class instances. 


Bring up this window by placing your cursor on an object or class 
instance in the Module window, then pressing Ct/-l. 


[sJ= 
@75C6:01 


{ 
class TextWindow Z | 


Most Turbo Debugger data record Inspector windows have two 
panes: a top pane summarizing the record’s field names/members 
and their current values, and a bottom pane displaying the type of 
the field or member highlighted in the top pane. An object/class 
instance Inspector window provides both of those panes, and also 
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The object/class 
instance 
Inspector window 
local menus 


Range... 


Change... 


Methods 


a third pane between them. This third pane summarizes the 
instance’s methods or member functions, with the code address of 
each. (The code address takes into account polymorphic objects 
and the VMT.) 


Each of the top two panes of the object /class instance Inspector 
window has its own local menu, displayed by pressing Alf-F10 in 
that pane. Use the control-key shortcuts to get to individual menu 
items if you've enabled hot keys with TDINST. 


Range... 
Change... 
Methods es 
Show inherited Yes 


Inspect 

Descend 

New expression... 
Type cast 
Hierarchy 


As with record Inspector windows, the bottom pane serves only 
to display the type of the highlighted field and doesn’t have a 
local menu. 


The top pane, which summarizes the data fields or members for 
the selected item, are described here. 


This command is unchanged from earlier versions. It displays the 
range of array items. If the inspected item is not an array or a 
pointer, the item cannot be accessed. 


By choosing this command, you can load a new value into the 
highlighted data field or member. This command is also 
unchanged from earlier versions of Turbo Debugger. 


This command is a Yes/No toggle, with Yes as the default condi- 
tion. When it is set to Yes, methods or member functions are sum- 
marized in the middle pane. When it is set to No, the middle pane 
does not appear. This toggle is remembered by the next Inspector 
window to be opened. 


Chapter 10, C++ and object-oriented Pascal debugging 161 


open a separate Inspector 
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Show Inherited 


Inspect 


Descend 


Use Descend fo inspect a 
complex data structure 
when you don’t want to 


window for each item. 


New Expression... 


Type Cast... 


Hierarchy 


The middie and 
bottom panes 


This command is also a Yes/No toggle. When it is set to Yes, all 
data fields or members and all methods or member functions are 
shown, whether they are defined within the type being inspected 
or inherited from an ancestor type. When it is set to No, only those 
fields and methods defined within the type being inspected are 
displayed. 


As with earlier versions of Turbo Debugger, choosing this 
command opens an Inspector window on the highlighted field or 
member. Pressing Enter over a highlighted field or member does 
the same thing. 


This command has not changed from earlier versions of Turbo 
Debugger. The highlighted item takes the place of the item in the 
current Inspector window. No new Inspector window is opened. 
However, you cannot return to the previously inspected field, as 
you could if you had used the Inspect option. 


No change from earlier versions. This command prompts you for 
a new data item or expression to inspect. The new item replaces 
the current one in the window; it doesn’t open another window. 


Lets you specify a different data type (Byte, Word, Int, Char 
pointer) for the item being inspected. This is useful if the 
Inspector window contains a symbol for which there is no type 
information, as well as for explicitly setting the type for untyped 
pointers. 


When you choose this command, an Hierarchy window opens. 
For a full description of this window, see page 155. 


The middle pane summarizes the methods of an object or the 
member functions of a class. The only difference between the 
Object Method pane’s local menu and the local menu for the top 
pane is the absence of the Change command. Unlike data fields 
and members, methods and member functions cannot be changed 
during execution, so there is no need for this command. 
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The bottom pane displays the type of the item highlighted in the 
upper two windows. 
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Assembler-level debugging 


This chapter is for programmers who are familiar with pro- 
gramming the 80x86 processor family in assembler. 


_ You don’tneed to use the We explain when you might want to use assembler-level debug- 
ee ee ied tiara ging and describe the CPU window with its built-in disassembler 
fete peas problems and assembler. You then learn how to examine and modify raw 

that may be easier to find hex data bytes, how to peruse the function calling stack, how to 
using techniques discussed in examine and modify the CPU registers, and finally how to 


this chapter. examine and modify the CPU flags. 


When source debugging isn’t enough 


When you are debugging a program, most of the time you refer to 
data and code at the source level; you refer to symbol names 
exactly as you typed them in your source code, and you proceed 
through your program by executing pieces of source code. 


Sometimes, however, you can gain insight into a problem by 
looking at the exact instructions that the compiler generated, the 
contents of the CPU registers, and the contents of the stack. To do 
this, you need to be familiar with both the 80x86 family of proces- 
sors and with how the compiler turns your source code into 
machine instructions. Because many excellent books are available 
about the internal workings of the CPU, we won’t go into that in 
detail here. You can quickly learn how the compiler turns your 
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source code into machine instructions by looking at the 
instructions generated for each line of source code. 


C and Pascal, for example, let you write lines of source code that 
perform many actions at once, and Turbo Debugger lets you step 
one source line at a time, not one expression at a time. However, 
you sometimes want to know the result of executing a small piece 
of one source line. By stepping through your program one 
machine instruction at a time, you can examine intermediate 
results, although it does require some effort to figure out how the 
compiler translated your source statements into machine code. 


The CPU window 
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Figure 11.1] 
The CPU window 


The CPU window shows you the entire state of the CPU. You can 
examine and change the bits and bytes that make up your pro- 
gram’s code and data. You can use the built-in assembler in the 
Code pane to patch your program temporarily by entering 
instructions exactly as you would type assembler source state- 
ments. You can also access the underlying bytes of any data struc- 
ture, display them in a number of formats, and change them. 


——————_—_—_—_ Sang 
{ program } a ax 0000 
cs:084E>9A00004B62 call 624B:0000 ® bx 0000 
cs:0853 9AAE164B62 call 624B:16AE 
cs:0858 55 bp 
cs:0859 89E5 bp,sp 
cs:085B 81£C0001 sp,0100 
TPDEMO.218: Init; 
H cs:O085F E8A0FB TPDEMO. INIT 
TPDEMO.219: Buffer := GetLine; 
cs:0862 8DBEOOFF lea di, [bp-0100] 
cs:0866 16 push ss 
cs:0867 57 push di 
cs:0868 E83BFD TPDEMO. 


A FO FE a Uze 24004 0000 
7C 01 ¢effo"1lo 34002 0000 
E2 1D “18eR+fo 24000 0000 

FF cco v 33FFE>0000 


Open a CPU window by choosing View! CPU from the menu bar. 
Depending on what you are viewing in the current window, the 
new CPU window comes up positioned at the appropriate code, 
data, or stack location. This provides a convenient method for 
taking a “low-level” look at the code, data, or stack location your 
cursor is currently on. 


The following table shows where your cursor will be positioned 
when you choose the CPU command: 
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CPU 


Current window window pane Position 

Stack window Stack Current SS:SP 

Module window Code Current CS:IP 

Variable window Data* Address of item 

Inspector window Data Address of item 

Breakpoint Code Breakpoint address 
(if not global) 


*Code pane, if item in window is a routine 


CPU windows have five panes. To go from one pane to the next, 
press Tab or Shift-Tab, or click the pane with your mouse. The line 
at the top of the CPU window shows what processor type you 
have (8086, 80286, 80386, or 80486). The top left pane (Code pane) 
shows the disassembled program code intermixed with the source 
lines. The second top pane (Register pane) shows the contents of 
the CPU registers. The right pane is the Flags pane, showing the 
state of the eight CPU flags. The bottom left pane (Data pane) 
shows a raw hex dump of any area of memory you choose. The 
bottom right pane (Stack pane) shows the contents of the stack. 


In the Code pane, an arrow (>) shows the current program loca- 
tion (CS:IP). In the Stack pane, an arrow (>) shows the current 
stack pointer (SS:SP). 


If the highlighted instruction in the Code pane references a 
memory location, the memory address and its current contents 
are displayed on the top line of the CPU window. This lets you 
see both where an instruction operand points in memory and the 
value that is about to be read or written over. 


The Flags pane shows the value of each of the CPU flags. 


As with all windows and panes, pressing Alt-F10 pops up the Code 
pane local menu or, if control-key shortcuts are enabled, the Ctrl 
key with the first letter of the desired command gets you to it. 


In the Code, Data, and Stack panes, you can press Cirl) and Ctrl T 
to shift the starting display address of the pane by 1 byte up or 
down. This is easier than using the Goto command if you just 
want to adjust the display slightly. 
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The Code pane 


The disassembler 
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This pane shows the disassembled instructions at an address that 
you choose. 


The left part of each disassembled line shows the address of the 
instruction. The address is displayed either as a hex segment and 
offset, or with the segment value replaced with the CS register 
name if the segment value is the same as the current CS register. If 
the window is wide enough (zoomed or resized), the bytes that 
make up the instruction are displayed. The disassembled instruc- 
tion appears to the right. 


The Code pane automatically disassembles and displays your 
program instructions. If an address corresponds to either a global 
symbol, static symbol, or a line number, the line before the dis- 
assembled instruction displays the symbol if the Mixed display 
mode is set to Yes. Also, if there is a line of source code that corre- 
sponds to the symbol address, it is displayed after the symbol. 


Global symbols appear simply as the symbol name. Static symbols 
appear as the module name, followed by a pound sign (#) ora 
period (.), followed by the static symbol name. Line numbers 
appear as the module name, followed by a pound sign (#) ora 
period (.), followed by the decimal line number. 


When an immediate operand is displayed, you can infer its size 
from the number of digits: A byte immediate has 2 digits, and a 
word immediate has 4 digits. 


Turbo Debugger can detect an 8087, 80287, or 80387 numeric 
coprocessor and disassemble those instructions if a floating-point 
chip or emulator is present. 


The instruction mnemonic RETF indicates that this is a far return 
instruction. The normal RET mnemonic indicates a near return. 


Where possible, the target of JMP and CALL instructions is 
displayed symbolically. If CS:IP is a JMP or conditional jump 
instruction, an arrow (7 or J) that shows jump direction will be 
displayed only if the executing instruction will cause the jump to 
occur. Also, memory addresses used by MOV, ADD, and other 
instructions display symbolic addresses. 
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The Code pane 


local menu If you don’t come up in the Code pane, use Tab or Shift-Tab to get 
there. Then press Alt-F10 to bring up the local menu. 


View source 
Mixed Yes 


New cs:ip 
Assemble... 
1/0 


> 


Goto After choosing this command, you're prompted for the new 
address to go to. You can enter addresses that are outside of your 
program, to examine code in the BIOS ROM, inside DOS, and in 
resident utilities. See Chapter 9 for complete information on 
entering addresses. 


The Previous command restores the Code pane to the position it 
had before the Goto command was issued. 


Origin Positions you at the current program location as indicated by the 
CS:IP register pair. This command is useful when you want to 
return to where you started. 


The Previous command restores the Code pane to the position it 
had before the Origin command was issued. 


Follow Positions you at the destination address of the currently high- 
lighted instruction. The Code pane is repositioned to display the 
code at the address where the currently highlighted instruction 
will transfer control. For conditional jumps, the address is shown 
as if the jump occurred. 


This command can be used with the CALL, JMP, conditional jump 
(JZ, JNE, LOOP, JCXZ, and so forth) and INT instructions. 


The Previous command restores the Code pane to the position it 
had before the Follow command was selected. 
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Caller Positions you at the instruction that called the current interrupt or 
subroutine. 


This command won’t always work. If the interrupt routine or 
subroutine has pushed data items onto the stack, sometimes 
Turbo Debugger can’t figure out where the routine was called 
from. 


The Previous command restores the Code pane to the position it 
had before the Caller command was selected. 


Previous Restores the Code pane position to the address before the last 
command that explicitly changed the display address. Using the 
arrow keys and PgUp and PgDn does not cause the position to be 
remembered. 


When you choose Previous, the Code pane position is remem- 
bered, so that repeated use of the Previous command causes the 
Code pane to switch back and forth between two addresses. 


Search Lets you enter an instruction or byte list to search for. Enter an 
instruction exactly as you would with the Assemble command. 


Be careful which instructions you try to search for; you should 
only search for instructions that don’t change the bytes they 
assemble to, depending on their location in memory. For example, 
searching for the following instructions is no problem: 


PUSH DX 
POP = [DI+4] 
ADD AX,100 


but searching for the following instructions can cause unpre- 
dictable results: 


JE 123 
CALL MYFUNC 
LOOP 100 


You can also enter a byte list instead of an instruction. See 
Chapter 9 for more on entering byte lists. 
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Mixed Toggles between the three ways of displaying disassembled 
instructions and source code: 


No No source code is displayed, only disassembled 
instructions. 


Yes Source code lines appear before the first disassembled 
instruction for that source line. The pane is set to this 
display mode if your current module is a high-level 
language source module. 


Both Source code lines replace disassembled lines for those 
lines that have corresponding source code; otherwise, the 
disassembled instruction appears. Use this mode when 
you are debugging an assembler module, and you want 
to see the original source code, instead of the correspond- 
ing disassembled instruction. The pane is set to this 
display mode if your current module is an assembler 
source module. 


New CS:IP_ Sets the program location counter (CS:IP registers) to the current- 
ly highlighted address. When you rerun your program, execution 
starts at this address. This is useful when you want to skip over a 
piece of code without executing it. 


> Use this command with extreme care. If you adjust the CS:IP toa 
location where the stack is in a different state than at the current 
CS:IP, you will almost certainly crash your program. Do not use 
this command to set the CS:IP to an address outside of the current 
routine. 


Assemble... | Assembles an instruction, replacing the one at the currently 
highlighted location. You are prompted for the instruction to 
assemble. See the section called “The assembler” in this chapter 
(page 180) for more details. 


You can also invoke this command by simply starting to type the 
statement you want to assemble. When you do this, a dialog box 
appears exactly as if you had specified Assemble. 
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I/O Reads or writes a value in the CPU’s I/O space and lets you 
examine the contents of I/O registers on cards and write things to 


In byte ; 
Out byte them. 


shar It pops up this menu. 


In Byte 


Reads a byte from an I/O port. You are prompted for the I/O port 
whose value you want to examine. Use the Read Word option to 
read from a word-sized I/O port. 


Out Byte 
Writes a byte to an I/O port. You are prompted for the I/O port 


to write to and the value you want to write. Use the Write Word 
option to write to a word-sized I/O port. 


Read Word 


Reads a word from an I/O port. You are prompted for the I/O 
port whose value you want to examine. Use the In Byte option to 
read from a byte-sized I/O port. 


Write Word 


Writes a word to an I/O port. You are prompted for the I/O port 
to write to and the value you want to write. Use the Out Byte 
option to write to a byte-sized I/O port. 


IN and OUT instructions access the I/O space where peripheral 
device controllers (such as serial cards, disk controllers, and video 
adapters) reside. 


C> Be careful when you use these commands. Some I/O devices consider 
reading their ports to be a significant event that causes the device 
to perform some action, such as resetting status bits or loading a 
new data byte into the port. You may disrupt the normal 
operation of the program you are debugging or the device with 
indiscriminate use of these commands. 
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The Register and Flags panes 


The Register pane 
local menu 


Increment 


Decrement 
Zero 


Change... 


The Register pane, which is the top pane to the right of the Code 
pane, shows the contents of the CPU registers. 


The top right pane is the Flags pane, which shows the state of the 
eight CPU flags. The following table lists the different flags and 
how they are shown in the Flags pane: 


Letter in pane Flag name 


Carry 

Zero 

Sign 

Overflow 

Parity 
Auxiliary carry 
Interrupt enable 
Direction 


a agowmnNnn 


Press Alt-F10 to pop up the Register pane local menu. Or, if 
control-key shortcuts are enabled, use the Ctrl key with the first 
letter of the desired command to access the command. 


Increment 
Decrement 


Zero 
Change... 
Registers 32-bit No 


Adds 1 to the value in the currently highlighted register. This is an 
easy way to make small adjustments in the value of a register to 
compensate for “off-by-one” bugs. 


Subtracts 1 from the value in the currently highlighted register. 
Sets the value of the currently highlighted register to 0. 


Changes the value of the currently highlighted register. You are 
prompted for the new value. You can make full use of the expres- 
sion evaluator to enter a new value. 
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The Data pane 


Registers 32-bit 


The Flags pane 
local menu 


Toggle 


You can also invoke this command by simply starting to type the 
new value for the register. A dialog box appears exactly as if you 
had specified the Change command. 


On an 80386 processor, toggles between displaying the CPU 
registers as 16-bit or 32-bit values. You will usually see 16-bit 
registers, unless you use this command to set the display to 32-bit 
registers. You really need to see 32-bit registers only if you’re de- 
bugging a program that uses the 32-bit addressing capabilities of 
the 386 chip. If you are debugging an ordinary program that uses 
only normal 16-bit addressing, use the 16-bit register display. 


Press Alt-F10 to pop up the Flags pane local menu or, if control-key 
shortcuts are enabled, use the Ctrl key with the first letter of the 
desired command to access the command. 


Sets the value of the flag to 0 if it was 1, and to 1 if it was 0. The 
value 0 corresponds to “clear,” and 1 indicates “set.” You can also 
press Enter to toggle the value of the currently highlighted flag. 
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This pane shows a raw display of an area of memory you've 
selected. The leftmost part of each line shows the address of the 
data displayed in that line. The address is displayed either as a 
hex segment and offset, or with the segment value replaced with 
the DS register name if the segment value is the same as the 
current DS register. 


Next, the raw display of one or more data items is displayed. The 
format of this area depends on the display format selected with 
the Display As local menu command. If you choose one of the 
floating-point display formats (Comp, Float, Real, Double, 
Extended), a single floating-point number is displayed on each 
line. Byte format displays 8 bytes per line, Word format displays 4 
words per line, and Long format displays 2 long words per line. 


When the data is displayed as bytes, the rightmost part of each 
line shows the display characters that correspond to the data 
bytes displayed. Turbo Debugger displays all byte values as their 
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display equivalents, so don’t be surprised if you see funny 
symbols displayed to the right of the hex dump area—these are 
just the display equivalents of the hex byte values. 


> If you use the Data pane to examine the contents of the display 
memory, the ROM BIOS data area, or the vectors in low memory, 
you will see the values that are there when the program being 
debugged runs, not the actual values in memory when Turbo 
Debugger is running. These are not the same values that are in 
these memory areas at the time you look at them. Turbo De- 
bugger detects when you're accessing areas of memory that it 
uses as well, and it gets the correct data value from where it stores 
the user program's copy of these data areas. 


The Data pane 


local Menu Once you are positioned in the Data pane, press Alt-F10 to pop up 
the local menu or, if control-key shortcuts are enabled, use the Ctrl 
key with the first letter of the desired command to access it. 


Goto 

Search 

Next 

Change 
Follow > 
Previous 


Display as > 
Block > 


Goto Positions you at an address in your data. Enter the new address 
you want to go to. You can enter addresses inside DOS, in resi- 
dent utilities, or outside of your program, which lets you examine 
data in the BIOS data area. See Chapter 9 for a complete 
discussion of how to enter addresses. 


search Searches fora character string, starting at the current memory 
address as indicated by the cursor position. Enter the byte list to 
search for. The search does not wrap around from the end of the 
segment to the beginning. See Chapter 9 for a complete discussion 
of byte lists. 
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Next 


Change... 


Follow 


Searches for the next instance of the byte list you previously 
specified with the Search command. 


Lets you change the bytes at the current cursor location. If you’re 
over an ASCII display or the format is Byte, you’re prompted for 
a byte list. Otherwise, you’re prompted for an item of the current 
display type. See Chapter 9 for a discussion of byte lists. 


You can also invoke this command by simply starting to type the 
new value or values. This brings up a dialog box exactly as if you 
had chosen the Change command. 


This command opens a menu that lets you follow near or far 
pointer chains. 


Near code 
Far code 


Offset to data 
Segment:offset to data 
Base segment:0 to data 


Near Code 


This command interprets the word under the cursor in the Data 
pane as an offset into the current code segment as specified by the 
CS register. The Code pane becomes the current pane and is posi- 
tioned to this address. 


Far Code 


This command interprets the doubleword under the cursor in the 
Data pane as a far address (segment and offset). The Code pane 
becomes the current pane and is positioned to this address. 


Offset to Data 


This command lets you follow word (near, offset only) pointer 
chains. The Data pane is set to the offset specified by the word in 
memory at the current cursor location. 
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Previous 


Display As 


Byte 
Word 
Long 
Comp 


Float 
Real 
Double 
Extended 


Segment:Offset to Data 


This command lets you follow long (far, segment, and offset) 
pointer chains. The Data pane is set to the offset specified by the 
two words in memory at the current cursor location. 


Base Segment:0 to Data 


This command interprets the word under the cursor as a segment 
address and positions the Data pane to the start of that segment. 


Restores the Data pane address to the address before the last 
command that explicitly changed the display address. Using the 
arrow keys and PgUp and PgDn does not cause the position to be 
remembered. 


Turbo Debugger maintains a stack of the last five addresses, so 
you can backtrack through multiple uses of the Follow menu or 
Goto commands. 


Lets you choose how data appears in the Data pane. You can 
choose from any data format used by C, Pascal, and assembler. 
The menu options are described here. 


Byte 


Sets the Data pane to display as hexadecimal bytes. This 
corresponds to the C char data type, the Pascal double type, and 
the Pascal Byte type. 


Word 


Sets the Data pane to display as word hexadecimal numbers. The 
2-byte hexadecimal value is shown. This corresponds to the C int 
data type and the Pascal Word type. 


Long 


Sets the Data pane to display as long hexadecimal integers. The 
4-byte hex value is shown. This corresponds to the C long data 
type and the Pascal Longint type. 
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Block 


Comp 


Sets the Data pane to display 8-byte integers. The decimal value of 
the integer is shown. This is the Pascal Comp (IEEE) data type. 


Float 


Sets the Data pane to display as short floating-point numbers. The 
scientific notation floating-point value is shown. This is the same 
as the C float data type and the Pascal Single (IEEE) type. 


Real 


Sets the Data pane to display Pascal's 6-byte floating-point 
numbers. The scientific notation floating-point value is shown. 
This is the Pascal Real type. 


Double 


Sets the data pane to display 8-byte floating-point numbers. The 
scientific notation floating-point value is shown. This is the same 
as the C long double data type, the Pascal Double type, and the 
assembler TBYTE type. 


Extended 


Sets the Data pane to display 10-byte floating-point numbers. The 
scientific notation floating-point value is shown. This is the 
internal format used by the 80x87 coprocessor. It also corresponds 
to the C long double data type and the Pascal Extended (IEEE) 


type. 


Lets you manipulate blocks of memory. You can move, clear and 
set memory blocks, and read and write memory blocks to and 
from disk files. Block brings up the pop-up menu shown. 


Clear 


Sets a contiguous block of memory to zero (0). You are prompted 
for the address and the number of bytes to clear. 
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The Stack pane 


Move 


Copies a block of memory from one address to another. You are 
prompted for the source address, the destination address, and 
how many bytes to copy. 


Set 


Sets a contiguous block of memory to a specific byte value. You 
are prompted for the address of the block, how many bytes to set, 
and the value to set them to. 


Read 


Reads all or a portion of a file into a block of memory. You are 
prompted first for the file name to read from, then for the address 
to read it into, and finally for how many bytes to read. 


Write 


Writes a block of memory to a file. You are prompted first for the 
file name to write to, then for the address of the block to write and 
how many bytes to write. 


The Stack pane 
local menu 


The Stack pane, in the lower right corner of the CPU window, 
shows the contents of the stack. 


At the Stack pane, press Alt-F10 to pop up the local menu or, if 
control-key shortcuts are enabled, use the Ctr key with the first 
letter of the desired command to access the command. 


Gote 
Origin 
Follow 
Previous 


Change... 
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Goto 


Origin 


Follow 


Previous 


Change 


The assembler 


Positions you at an address in the stack. Enter the new stack 
address. If you want, you can enter addresses outside your pro- 
gram’s stack, although you would usually use the Data pane to 
examine arbitrary data outside your program. See Chapter 9 for 
information about how to enter addresses. 


The Previous command restores the Stack pane to the position it 
had before the Goto command was issued. 


Positions you at the current stack location as indicated by the 
SS:SP register pair. This command is useful when you want to 
return to where you started. 


The Previous command restores the Stack pane to the position it 
had before the Origin command was issued. 


Positions you at the word in the stack pointed to by the currently 
highlighted word. This is useful for following stack-frame threads 
back to a calling function. 


The Previous command restores the Stack pane to the position it 
had before the Follow command was issued. 


Restores the Stack pane position to the address before the last 
command that explicitly changed the display address. Using the 
arrow keys and PgUp and PgDn does not cause the position to be 
remembered. 


Repeated use of the Previous command causes the Stack pane to 
switch back and forth between two addresses. 


Lets you enter a new word value for the currently highlighted 
stack word. 


You can also invoke this command by simply starting to type the 
new value for the highlighted stack item. A dialog box will 
appear, exactly as if you had specified the Change command. 
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Via the Assemble command in the Code pane local menu, Turbo 
Debugger lets you assemble instructions for the 8086, 80186, 
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80286, 80386, and 80486 processors, and also for the 8087, 80287, 
and 80387 numeric coprocessors. 


When you use Turbo Debugger’s built-in assembler to modify 
your program, the changes you make are not permanent. If you 
reload your program using the Run | Program Reset command, or 
if you load another program using the File | Open command, 
you'll lose any changes you’ve made. 


Normally you use the assembler to test an idea for fixing your 
program. Once you've verified that the change works, you must 
change your source code and recompile and link your program. 


The following sections describes the differences between the 
built-in assembler and the syntax accepted by Turbo Assembler. 


Operand address 


size Overrides For the call (CALL), jump (JMP), and conditional jump (JNE, JL, 
and so forth) instructions, the assembler automatically generates 
the smallest instruction that can reach the destination address. 
You can use the NEAR and FAR overrides before the destination 
address to assemble the instruction with a specific size. For 
example, 


CALL FAR XYZ 
JMP NEAR Al 


Memory and_ When you use a symbol from your program as an instruction 
immediate operands operand, you must tell the built-in assembler whether you mean 
the contents of the symbol or the address of the symbol. If you use 
just the symbol name, the assembler treats it as an address, exact- 
ly as if you had used the assembler OFFSET operator before it. If 
you put the symbol inside brackets ([ ]), it becomes a memory 
reference. For example, if your program contains the data 
definition 
A DW 4 

then [A] references the area of memory where A is stored. 


When you assemble an instruction or evaluate an assembler 
expression to refer to the contents of a variable, use the name of 
the variable alone or between brackets: 


mov dx,a 
mov ax, [a] 
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Operand data 
size overrides 


String instructions 


To refer to the address of the variable, use the OFFSET operator: 


mov ax,offset a 


For some instructions, you must specify the operand size using 
one of the following expressions before the operand: 


BYTE PTR 
WORD PTR 


Here are examples of instructions using these overrides: 


add BYTE PTR[si],10 
mov WORD PTR[bp+10],99 


In addition to these size overrides, you can use the following 
overrides to assemble 8087 /80287/80387 numeric coprocessor 
instructions: 


DWORD PTR 
QWORD PTR 
TBYTE PTR 


Here are some examples using these overrides: 


fild QWORD PTR[bx] 
stp TBYTE PTR[bp+4] 


When you assemble a string instruction, you must include the 
size (byte or word) as part of the instruction mnemonic. The 
assembler does not accept the form of the string instructions that 
uses a sizeless mnemonic with an operand that specifies the size. 
For example, use STOSW rather than STOS WORD PTR{dil. 


The Dump window 


Figure 11.2 
The Dump window 
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The Dump window shows you a raw data dump of any area of 
memory. It works exactly like the Data pane in the CPU window. 
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See “The Data pane local menu” section earlier in this chapter 
(page 175) for a description of the contents and local menu for this 
window. 


Typically, you’d use this window when you’re debugging an 

assembler program at the source level, and you want to take a 
low-level look at some data areas. Use View | Dump to open a 
Dump window. 


You can also use this window if you’re in an Inspector window, 
and you want to look at the raw bytes that make up the object you 
are inspecting. Use View | Dump to get a Dump window that’s 
positioned to the data in the Inspector window. 


The Registers window 


Figure 11.3 
Tne Registers window 


You can shrink the size of 
your Module window and 
put up a Registers window 
alongside If. 


The Registers window shows you the contents of the CPU 
registers and flags. It works like a combination of the Registers 
and Flags panes in the CPU window. 


See “The Register pane local menu” (page 173) and “The Flags 
pane local menu” (page 174) sections earlier in this chapter for a 
description of the contents and local menus for this window. 


Use this window when you're debugging an assembler program 
at the source level and want to look at the register values. 


Turbo C code generation 


The Turbo C compiler does a number of predictable things when 
it generates machine code. Once you become familiar with the 
compiler, you'll quickly see exactly how the machine instructions 
correspond to your source code. 
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Function return values are placed in the following registers: 


Return type Register(s) 
int AX 

long DX:AX 
float STO) 
double ST(0) 

long double ST(0) 

near * AX 

far * DX:AX 


The compiler places heavily used int and near pointers into regis- 
ters, using first the SI register, then the DI register. 


Your autovariables and function-calling parameters are accessed 
from SS:BP. 


The AX, BX, CX, and DX registers are not necessarily preserved 
across function calls. 


Registers are always used as word registers, not as byte registers, 
even if you use char data types. 


Switch statements can be compiled into one of three forms, 
depending on which will produce the most efficient code: 


m conditional jumps as if the switch were an if...else chain 
ma jump table of code addresses 
wa jump table of switch values and code addresses 


Refer to your Turbo C manuals for more information on Turbo C 
code generation. 
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The 80x87 coprocessor chip and 
emulator 


This chapter is for pro- If your program uses floating-point numbers, Turbo Debugger 
Onde ae lets you examine and change the state of the numeric coprocessor 
80x87 peace coprocessor, OF software emulator. You don’t need to use the capabilities 

described in this chapter to debug programs that use floating- 
point numbers, although some very subtle bugs may be easier to 
find. 
In this chapter, we discuss the differences between the 80x87 chip 
and the software emulator. We also describe the Numeric 
Processor window and show you how to examine and modify the 
floating-point registers, the status bits, and the control bits. 


The 80x87 chip vs. the emulator 


Turbo Debugger automatically detects whether your program is 
using the math chip or the emulator and adjusts its behavior 
accordingly. 


Note that most programs use either the emulator or the math 
chip, not both within the same program. If you have written 
special assembler code that uses both, Turbo Debugger won’t be 
able to show you the status of the math chip; it will report on the 
emulator only. 
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The Numeric Processor window 


Figure 12.1 
The Numeric Processor 
window 


The Register pane 


The 80-bit floating-point 
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registers 


You create a Numeric Processor window by choosing the View | 
Numeric Processor command from the menu bar. The line at the 
top of the window shows the current instruction pointer, data 
pointer, and instruction opcode. The data pointer and instructions 
pointer are both shown as 20-bit physical addresses. You can con- 
vert these addresses to a segment and offset form by using the 
first four digits as the segment value, and the last digit as the 
offset value. 


For example, if the top line shows IPTR=5A669, you can treat this as 
the address 5a66:9 if you want to examine the current data and 
instruction in a CPU window. This window has three panes: The 
left pane (Register pane) shows the contents of the floating-point 
registers, the middle pane (Control pane) shows the control flags, 
and the right pane (Status pane) shows the status flags. 


[=]=Emulator IPTR=00000 OPCODE=000 OPTR=00003=[1] [+] 
ST(0 im=0 | ie=0 
dm=0 | de=0 § 


Empty ST(7 


The top line shows you information about the last floating-point 
operation that was executed. The IPTR shows the 20-bit physical 
address from which the last floating-point instruction was 
fetched. The OPCODE shows the instruction type that was 
fetched. The OPTR shows the 20-bit physical address of the 
memory address that the instruction referenced, if any. 


The Register pane shows each of the floating-point registers, ST(0) 
to ST(7), along with its status (valid /zero/special/empty). The 
contents are shown as an 80-bit floating-point number. 


If you’ve zoomed the Numeric Processor window (by pressing F5) 
or made it wider by using Window | Size/Move, you'll also see 
the floating-point registers displayed as raw hex bytes. 
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The Register pane local 
menu 


Zero 
Empty 
Change 


The Control pane 


The control bits 


To bring up the Register pane local menu, press Alf-F10, or use the 
Cirl key with the first letter of the desired command to directly 
access the command. 


Zero 


Sets the value of the currently highlighted register to zero. 


Empty 


Sets the value of the currently highlighted register to empty. This 
is a special status that indicates that the register no longer 
contains valid data. 


Change 


Loads a new value into the currently highlighted register. You are 
prompted for the value to load. You can enter an integer or float- 
ing-point value, using the current language’s expression parser. 
The value you enter will be automatically converted to the 80-bit 
temporary real format used by the numeric coprocessor. 


You can also invoke this command by simply starting to type the 
new value for the floating-point register. A dialog box will appear 
exactly as if you had specified the Change command. 


The following table lists the different control flags and how they 
appear in the Control pane: 


Name in pane Flag description 
im Invalid operation mask 
dm Denormalized operand mask 
zm Zero divide mask 
om Overflow mask 
um Underflow mask 
pm Precision mask 
iem Interrupt enable mask (8087 only) 
pe Precision control 
rc Rounding control 
ic Infinity control 
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The Control pane local 


-menu 


The Status pane 


The status bits 


The Status pane local 
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menu 


Press Tab to go to the Control pane, then press Alf-F10 to pop up 
the local menu. (Alternatively, you can use the Cirl key with the 
first letter of the desired command to access it.) 


Toggle 


Cycles through the values that the currently highlighted control 
flag can be set to. Most flags can only be set or cleared (0 or 1), so 
this command just toggles the flag to the other value. Some other 
flags have more than two values; for those flags, this command 
increments the flag value until the maximum value is reached, 
and then it sets it back to zero. 


You can also toggle the control flag values by highlighting them 
and pressing Enter. 


The following table lists the different status flags and how they 
appear in the Status pane: 


Name in pane Flag description 
ie Invalid operation 
de Denormalized operand 
ze Zero divide 
oe Overflow 
ue Underflow 
pe Precision 
ir Interrupt request 
cc Condition code 
st Stack top pointer 


Press Tab to move to the Status pane, then press Alt-F10 to 
pop up the local menu. (You can also use the Ctrl key with 
the first letter of the desired command to access the 
command directly.) 


Toggle 


Cycles through the values that the currently highlighted 
status flag can be set to. Most flags can only be set or cleared 
(0 or 1), so this command just toggles the flag to the other 
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value. Some other flags have more than two values; for 
those flags, this command increments the flag value until 
the maximum value is reached, and then sets it back to zero. 


You can also toggle the status flag values by highlighting 
them and pressing Enter. 
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Command reference 


Now that you've read about all the commands, here’s a quick 
summary. This chapter lists and describes 


w all the single-keystroke commands available on the function 
and other keys 


wall the menu bar commands and the commands for the local 
menu of each window type 


m keystrokes used in the two types of panes (those in which you 
enter text and those from which you select an item) 


g keystrokes for moving and resizing windows 


Hot keys 


A hot key is a key that performs its action no matter where you 
are in the Turbo Debugger environment. Table 13.1 on page 192 
lists all the hot keys. 
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Table 13.1 


The function key and hot key Key Menu command Function 
COmmManes FI Brings up context-sensitive help 

F2 Breakpoints!Toggle Sets breakpoint at cursor position 

F3 View | Module Module pick list 

F4 Run | Go to Cursor Runs to cursor position 

F5 Window | Zoom Zooms/unzooms current window 

F6 Window | Next Window Goes to next window 

Fe Run | Trace Into Executes single source line or 
instruction 

F8 Run | Step Over Executes single source line or 
instruction, skipping calls 

F9 Run! Run Runs program 

F10 Invokes the menu bar, takes you 


out of menus 


Alt-F1 Help| Previous Topic Brings up last help screen 


Alt-F2 Breakpoints | At Sets breakpoint at an address 

Alt-F3 Window | Close Closes current window 

Alt-F4 Run | Back Trace Reverses program execution 

Ak-F5 Window | User Screen Shows your program’s screen 

Alt-F6 Window |Undo Close Reopens the last-closed window 

Alt-F7 Run| instruction Trace Executes a single instruction 

Alt-F8 Run | Until Return Runs until return from function 

Alt-F9 Run | Execute To Runs to a specified address 

Alt-F10 Invokes the window’s local menu 

Alt-1—9 Switch to numbered window 1 
through 9 

Alt-Space Goes to the System menu 

Alt-B Goes to the Breakpoints menu 

Alt-D Goes to the Data menu 

Alt-F Goes to the File menu 

Alt-H Goes to the Help menu 

Ak-O Goes to the Options menu 

Ak-R Goes to the Run menu 

Alt-V Goes to the View menu 

Alt-W Goes to the Window menu 

Alt-X File! Quit Quits Turbo Debugger and returns 
you to DOS 

Altz | Options|Macros|Create Defines a keystroke macro 

Al- Options! Macros | Stop Ends a macro recording 

Recording 
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Table 13.1: 


Key Menu command 
Ctr-F2 Run! Program Reset 


Ctrl-F4 Datal Evaluate 
Ctrl-F5 Window | Size/Move 


Ctrl-F7 Datal Add Watch 


Ctrl-F8 Breakpoints | Toggle 
Ctri-F9 Run! Run 

Ctrl-F10 

Ctrl 


Ctrl — 


Ctrl-A 
Ctrl-C 
Ctrl-D 
Ctrl-E 
Ctrl-F 
Ctrl-R 
Ctrl-S 
Ctrl-X 


Shift-F1 Help | Index 
Shift-Tab 


Shift > 
Shift — 
Shift T 
Shift L 


Esc 


Ins 


Tab Window | Next Pane 
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The function key and hot key commands (continued) 


Function 


Stops debug session and resets the 
program to start again 

Evaluates an expression 

Initiates window moving or 
resizing 

Adds a variable to the Watches 
window 

Toggles a breakpoint at cursor 
Runs a program 

Invokes the window’s local menu 
Shifts the starting address ina 
Code, Data, or Stack pane ina CPU 
window 1 byte up 

Shifts the starting address ina 
Code, Data, or Stack pane in a CPU 
window 1 byte down 

Moves to previous word 

Scrolls down one screen 

Moves right one column 

Moves up one line 

Moves to next word 

Scrolls up one screen 

Moves left one column 

Moves down one line 


Goes to the index for online help 
Moves cursor to previous window 
pane or dialog box item 

Moves cursor between the panes 
in a window (the pane in the 
direction of the arrow becomes 
the active pane.) 


Closes an Inspector window, goes 
out of menus 

Starts text block selection 
(highlight); use <- and > to 
highlight 

Moves cursor to next window pane 
or dialog box item 
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Commands from the menu bar 


You invoke the menu bar by pressing the F10 key; you can then go 
directly to one of the individual menus by 

m cursoring to the menu title and pressing Enter 

@ pressing the highlighted letter of the menu title 

You can also open a menu directly (without first moving to the 


menu bar) by pressing Altin combination with the first letter of the 
menu name you desire. 
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The = System) 


menu Restore Standard Restores standard window 

layout 

Repaint Desktop Redisplays entire screen 

About Displays information about 
Turbo Debugger 

The File menu 

Open Opens a new program to debug 

Change Dir Changes to new disk or directory 

Get Info Displays program information 

DOS Shell Starts a DOS command processor 

Resident Causes Turbo Debugger to 
terminate and stay resident 

Symbol Load Loads symbol table independent of 
.EXE file 

Table Relocate Sets base segment of symbol table 

Quit Returns to DOS 

The View menu 

Breakpoints Displays breakpoints 

Stack Displays function-calling stack 

Log Displays log of events and data 

Watches Displays variables being watched 

Variables Displays global and local variables 

Module Displays program source module 

File Displays disk file as ASCII or hex 

CPU Displays CPU instructions, data, 
stack 

Dump Displays raw data dump 
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Tne Run menu 


The Breakpoints 
menu 


Tne Data menu 


Registers 
Numeric Processor 
Execution History 


Hierarchy 


Another 
Module 
Dump 
File 


Run 


Go To Cursor 
Trace Into 


Step Over 
Execute To 
Until Return 
Animate 
Back Trace 


Instruction Trace 
Arguments 


Program Reset 


Togele 
AE && 


Changed Memory Global 


Expression True Global 


Delete All 


Inspect 

Evaluate /Modify 
Add Watch 
Function Return 
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Displays CPU registers and flags 
Displays coprocessor or emulator 
Displays assembler code saved for 
backtracking or keystroke playback 
Displays object or class type list and 
hierarchy tree 


Makes another Module window 
Makes another Dump window 
Makes another File window 


Runs your program without 
stopping 

Runs to current cursor location 
Executes one source line or 
instruction 

Traces, skipping calls 

Runs to specified address 

Runs until function returns 
Continuously steps your program 
Reverses program execution for one 
source line or instruction 
Executes a single instruction 

Sets program command-line 
arguments 

Reloads current program 


eee breakpoint at cursor 
Sets breakpoint at specified address 


Sets global breakpoint on memory 
area 

Sets global breakpoint on 
expression 

Removes all breakpoints 


Inspects a data object 

Evaluates an expression 

Adds variable to Watches window 
Inspects current routine’s return 
value 
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The Options 
menu 


The Window 
menu 


The Help Menu 


Language 


Macros 
Create 
Stop Recording 
Remove 
Delete All 
Display Options 


Path for Source 
Save Options 


Restore Options 


Zoom 
Next 


Next Pane 
Size/Move 
Iconize/ Restore 


Close 

Undo Close 

Dump Pane to Log 
User Screen 

Open window list 


Window Pick 


Index 
Previous Topic 
Help on Help 


Sets expression language from 
source module 


Defines a keystroke macro 

Ends the recording session 
Removes a keystroke macro 
Removes all keystroke macros 
Lets you set screen display options 
(screen swapping, size, tabs) 
Directory list for source files 

Saves options, screen layout, and 
macros to disk 

Restores options from disk 


Zooms window to full screen size 
and back 

Activates successive windows open 
onscreen 

Goes to the next pane in a window 
Moves window or changes its size 
Reduces window to a small symbol 
or restores it 

Closes window 

Reopens the last window closed 
Writes current pane to Log window 
Displays your program output 
Displays list of open windows to 
activate 

Displays a menu of open menus, if 
more than 9 are open onscreen 


Goes to the index for online help 
Brings up last help screen 
Accesses online help on the help 
system 
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The local menu commands 


Each type of window and 
each pane within a window 
has a different local menu. 


The menus in this section are 
arranged in alphabetical 
order to make lookups easier. 


Breakpoints 
window 


The CPU window 
menus 


You invoke the local menu for the current window by pressing 
Alt-F10. If control-key shortcuts are enabled, you can go directly to 
one of the individual menu items by pressing the Ctrl key in 
combination with the first letter of the item you desire. (Use the 
installation program TDINST to enable control-key shortcuts, if 
they’ve been disabled.) 


The following sections describe the local menu for each window 
and pane. 


Some panes have shortcuts to commonly used commands on their 
local menu. In the following section, these special keys are listed 
before the menu commands for the pane to which they apply. In 


_ many panes, the Enter key is a shortcut to examining or changing 


the currently highlighted item. The Del key often invokes the local 
menu command that deletes the highlighted item. Some panes let 
you start typing letters or numbers without first invoking a local 
menu command. In these cases, the dialog box for one of the local 
menu items pops up to accept your input. 


The Breakpoints window has two panes, the List pane on the left 
and the Detail pane on the right. Only the List pane has a local 
menu. 


Set Options Sets breakpoint actions, conditions, 
pass count, and enable/disable 

Hardware Options Lets you set hardware breakpoints 

Add Adds a new breakpoint 

Remove Removes highlighted breakpoint 

Delete All Deletes all breakpoints 

Inspect Looks at code where breakpoint is 
set 


Delis the shortcut for Remove in this window. 


The CPU window has five panes, each with a local menu: the 
Code pane, the Data pane, the Stack pane, the Register pane, and 
the Flags pane. 
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Code pane 


Data pane 


Goto 
Origin 
Follow 


Caller 
Previous 
Search 

View Source 
Mixed 


New CS:IP 
Assemble 
in Byte 
Out Byte 
Read Word 
Write Word 


Goto 


Search 
Next 


Change 


Follow 
Near Code 


Far Code 
Offset to Data 
Segment:Offset to Data 
Base Segment:0 to Data 
Previous 
Display As 

Byte 


Word 
Long 


Displays code at new address 
Displays code at CS:IP 

Displays code at JMP or CALL 
target 

Displays code at calling function 
Displays code at last address 
Searches for instruction or bytes 
Switches to Module window 

Mixes source code with dis- 
assembly: No/Yes/Both 

Sets CS:IP to execute at new address 
Assembles instruction at cursor I/O 
Reads a byte from an I/O location 
Writes a byte to an I/O location 
Reads a word from an I/O location 
Writes a word to an I/O location 


Typing any character is a shortcut for the Assemble local menu 
command in this pane. 


Displays data at new address 
Searches for string or data bytes 


Searches again for next occurrence 
Changes data bytes at cursor 
address 


Sets Code pane to the near address 
under the cursor 

Sets Code pane to the far address 
under the cursor 

Sets Data pane to the near address 
under the cursor 

Sets Data pane to the far address 
under the cursor 

Sets Data pane to start of segment 
that contains the address under the 
cursor 

Displays data at last address 


Displays hex bytes 


Displays hex words 
Displays hex 32-bit long words 
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Comp Displays 8-byte Pascal comp 


integers 

Float Displays short (4-byte) floating- 
point numbers (Pascal singles, C 
floats) 

Real Displays 6-byte floating-point 
numbers (Pascal reals) 

Double Displays 8-byte floating-point 
numbers (Pascal and C doubles) 

Extended Displays 10-byte floating-point 
numbers (C long double, Pascal 
extended) 

Block 

Clear Sets memory block to zero 

Move Moves memory block 

Set Sets memory block to value 

Read Reads from file to memory 

Write Writes from memory to file 


Typing any character is a shortcut for the Change local menu 
command in this pane. 


Flags pane Toggle Sets or clears highlighted flag 


Pressing Enter or Spacebar is a shortcut for the Toggle local menu 
command in this pane. 


Register pane Increment Adds one to highlighted register 

Decrement Subtracts one from highlighted 
register 

Zero Clears highlighted register 

Change Sets highlighted register to new 
value 

Registers 32-bit Toggles 32-bit register display: No/ 
Yes 


Typing any character is a shortcut for the Change local menu 
command in this pane. 


Stack pane Goto Displays stack at new address 
Origin Displays data at SS:SP 
Follow Displays code pointed to by current 
item 
Previous Restores display to last address 
Change Allows you to edit information 
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Dump window 


File window 


Log window 
menu 


Module window 
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Typing any character is a shortcut for the Change local menu 


command in this pane. 


The Dump window is identical to the Data pane of the CPU 
window. Its local menu is identical to the Data pane local menu. 


The File window shows the contents of the disk file as hex bytes 


or as a disk file. 


Goto 
Search 
Next 
Display As 
File 

Edit 


Displays line number or hex offset 
Searches for string or data bytes 
Searches again for next occurrence 
Sets file display mode: ASCIT/Hex 
Switches to view new file 

Edits file or changes bytes at cursor 


Typing any character is a shortcut for the Search local menu 


command. 


The Log window shows messages sent to the log. 


Open Log File 
Close Log File 
Logging 

Add Comment 
Erase Log 


Starts logging to a file 
Stops logging to a file 
Toggles logging: No/Yes 
Writes user comment to log 
Clears all log messages 


Typing any character is a shortcut for the Add Comment local 


menu command. 


The Module window shows the source file for the program 


module. 


Inspect 
Watch 


Module 


Shows contents of variable under 
cursor 

Adds variable under cursor to 
watch list 

Changes to display different 
module 
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File Changes to display different file 


Previous Displays last module and position 

Line Displays source at line in module 

Search Searches for text string 

Next Searches for next occurrence of 
string 

Origin Displays current program location 

Goto Shows source or instructions at 
address 

Edit Starts editor to edit source file 


Typing any character is a shortcut for the Goto local menu 
command. 


Numeric 


Processor WINdOW The Numeric Processor window has three panes: the Register 
pane, the Status pane, and the Control pane. 


Register pane These are the local menu commands in this pane: 


Zero Clears the highlighted register 
Empty Sets the highlighted register to 
empty 
Change Sets the highlighted register to a 
| value 


Typing any character is a shortcut for the Change local menu 
command in this pane. 


Status pane = This is the local menu command in this pane: 
Toggle Cycles through valid flag values 


Pressing Enter is a shortcut for the Toggle local menu command in 
this pane. 


Control pane This is the local menu command in this pane: 
Toggle Cycles through valid flag values 


Pressing Enter is a shortcut for the Toggle local menu command in 
this pane. 
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Hierarchy window 


Object Type/Class List 
pane 


Hierarchy Tree pane 


Parent Tree pane 


Registers window 
menu 


Stack window 


Variables window 
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The Hierarchy window has two panes, the Object Type/Class List 
pane and the Hierarchy Tree pane. It also has a third pane, the 
Parent Tree pane, if you are running a C++ program with 
multiple inheritance. 


Inspect Shows contents of highlighted 
object or class type 

Tree Moves to the Hierarchy Tree pane 

Inspect Shows contents of highlighted 
object or class type 

Parents Toggles whether Parent Tree pane is 


displayed if you are running a C++ 
program with multiple inheritance 


Inspect Shows contents of highlighted 
object or class type 


The Registers window is identical to the Register and Flags panes 
of the CPU window. Its local menus are identical to the Register 
pane local menu and the Flags pane local menu. 


The Stack window shows the currently active functions. 


Inspect Shows source code for highlighted 
function 

Locals Shows local variables for 
highlighted function 


Pressing Enter is a shortcut for the Inspect local menu command. 


The Variables window has two panes, each with a local menu: 
The Global Symbol pane and the Local Symbol pane. 
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Global Symbol pane Inspect Shows contents of highlighted 


symbol 
Change Changes value of highlighted 
symbol 
Pressing Enter is a shortcut for the Inspect local menu command in 
this pane. 
Local Symbol pane Inspect Shows contents of highlighted 
symbol 
Change Changes value of highlighted 
symbol 


Pressing Enter is a shortcut for the Inspect local menu command in 
this pane. 


Watches window 


The Watches window has a single pane that shows the names and 
values of the variables you’re watching. 


Watch Adds a variable or expression to 
watch 

Edit Lets you edit a watch variable or 
expression 

Remove Deletes highlighted variable or 
expression 

Delete All Deletes all watch variables or 
expressions 

Inspect Shows contents of highlighted 
variable or expression 

Change Changes contents of highlighted 


variable; does not affect expressions 


The following keys are shortcuts to local menu commands in this 


window: 
any character Watch 
Enter Edit 
Del Remove 
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Inspector window 


An Inspector window shows the contents of a data item. 


Range Selects array members to inspect 

Change Changes the value of highlighted 
item 

inspect Opens new Inspector window for 

. highlighted item 

Descend Expands highlighted item into this 
Inspector window 

New Expression Inspects a new expression in this 
Inspector window 

Type Cast Type casts highlighted item to new 
type 


Object Type/ 


Class Inspector Object type/class Inspector windows have two panes that show 
window _ the contents (data fields or members, and methods or member 
functions) of an object or class. Their local menus, the same for 
both panes, are quite different from the local menu of regular 


Inspector windows. 
Inspect Shows the contents of the 
| highlighted type 
Hierarchy Returns to the Hierarchy window 
Show Inherited Toggles between showing all 


contents of object or class, and 
contents declared in current object 
or class 


Object/class 


instance  Object/class instance Inspector windows contain three panes, of 

| which only the first two have local menus. (The third displays 
Inspector window only the object type or class to which the instance belongs). Both 
local menus are the same, and contain the following commands: 


Range Selects array members to inspect 

Change Changes the value of highlighted 
item 

Methods Toggles whether methods or 


member functions are summarized 
in the middle pane 
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Show Inherited 


Inspect 

Descend 

New Expression 
Type Cast 


Hierarchy 


Toggles between showing all 
contents of object or class and 
contents declared in current object 
or class 

Opens new Inspector window for 
highlighted item 

Expands highlighted item into this 
Inspector window 

Inspects a new expression in this 
Inspector window 

Type casts highlighted data item to 
new type 

Returns to the Object Hierarchy 
window 


Text panes 

This is the generic name for a pane that displays the contents of a 

text file. The blinking cursor shows your current position in the 

file. The following table lists all the commands: 

Table 13.2 : 
Text pane key commands Key Function 

Ins Marks text block 
f Moves up one line 
L Moves down one line 
~ Moves right one column 
e Moves left one column 
Ctrl > Moves to next word 
Ctrl — Moves to previous word 
Home Goes to start of line 
End Goes to last character on line 
PgUp Scrolls up one screen 
PgDn Scrolls down one screen 
Ctrl-Home Goes to top line of pane 
Ctrl-End Goes to bottom line of pane 
Ctri-PgUp Goes to first line of file 
Ctrl-PgDn Goes to last line of file 


If you are not using the control-key shortcuts, you can also use the 
WordStar-style control keys for moving around a text pane. 
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List panes 


This is the generic name for a pane that lists information you can 
scroll through. A highlight bar shows your current position in the 
list. Here’s a list of all the commands available to you. 


Table 13.3 


List pane key commands Key Function 
T Moves up one item 
L Moves down one item 
> Scroll right 
e Scroll left 
Home Goes to start of line 
End Goes to last character on line 
PgUp Scrolls up one screen 
PgDn Scrolls down one screen 
Ctrl-Home Goes to top line of list pane 
Ctrl-End Goes to bottom line of list pane 
Ctrl-PgUp Goes to first item in list 
Ctrl-PgDn Goes to last item in list 
Backspace Backs up one character in incremental match 
Letter Makes incremental search (select by typing) 


You can also use the WordStar-style control keys for moving 
around a List pane. 


Commands in input and history list boxes 


The following table shows the commands available when you're 
inside an input or list box. 
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Table 13.4 
Dialog box key commands Key 


Ctrl 
Ctrl — 
Home 
End 
PgUp 
PgDn 
Ctrl-Home 
Ctrl-End 
Ctrl-PgUp 
Ctrl-PgDn 
Backspace 
Enter 

Del 

Esc 
Ctrl-N 


Function 


Moves up one list item 

Moves down one list item 

Moves right one character 

Moves left one character 

Moves to next word 

Moves to previous word 

Goes to start of line 

Goes to last character on line 

Scrolls up one screen 

Scrolls down one screen 

Goes to top line of list pane 

Goes to bottom line of list pane 

Goes to first item in list 

Goes to last item in list 

Deletes the character before the cursor 
Accepts your input and proceed 

Deletes the character at the cursor 

Cancels the dialog box and returns to menu 
Completes partially typed name in input box 


Window movement commands 


Table 13.5 
Window movement key 
commands Ctrl-F5 
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Function 


Toggles window-positioning mode 

Moves window up one line 

Moves window down one line 

Moves window right one column 

Moves window left one column 

Resizes window; moves bottom up 

Resizes window; moves bottom down 
Resizes window; moves right side away from left 
Resizes window; moves right side toward left 
Moves to left side of screen 

Moves to right side of screen 

Moves to top line of screen 

Moves to bottom line of screen 

Accepts current position 

Cancels window-positioning command 
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Wildcard search templates 


You can use wildcard search templates in two circumstances: 


m when you enter a file name to load or examine 
= when you enter a text search expression in a text pane 


The ? (question mark) matches any single character in the search 
expression. The * (asterisk) matches 0 or more characters in the 
search expression. 


Complete menu tree 


Figure 13.1 shows the complete structure of Turbo Debugger’s 
pull-down menus. 
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Figure 13.1: The Turbo Debugger menu tree 


Repaint desktop 
Restore standard 


Open... 
Change dir... 


Get info... 
DOS shell 


Resident 
Symbol load... 
Table relocate... 


Quit Alt-X 


Breakpoints 
Stack 

Log 

Watches 
Variables 


Numeric processor 
Execution history 
Hierarchy 
Another 


irs Mica 


Run 

Go to cursor 
Trace into 
Step over 


Execute to... 
Until return 


Animate... 


Back trace 


Alt-F8 
Alt-F4 


Instruction trace Alt-F7 


Arguments... 
Program reset 


Ctri-F2 


Breakpoints 


Toggle RS 
At Alt-F2 


Changed memory global... 
Expression true global... 


Hardware breakpoint... 
Delete all 


Inspect... 
Evaluate/modi fy... 


Add watch... 
Function return 


Module... 


Dump 
File... 
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Ctrl-F4 
Ctrl-F7 


Language... Source 
Macros 
Display options... 


Path for source... 


Save options... 
Restore options... 


Create... Alt = 
Stop recording Alt - 


Remove 
Delete al] 


Zoom 
Next 
Next pane 

Size/move 
Iconize/restore 

Close Alt-F3 
Undo close Alt-F6 


Dump pane to log 
User screen Alt-F5 
1 Module TPDEMO 

2 Watches 


Index Shi ft-F1 
Previous topic Alt-F1 
Help on help 
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How to debug a program 


Debugging is like the other phases of designing and imple- 
menting a program—part science and part art. There are specific 
procedures that you can use to track down a problem, but at the 
same time, a little intuition goes a long way toward making a long 
job shorter. 


The more programs you debug, the better you get at rapidly 
locating the source of problems in your code. You learn 
techniques that suit you well, and you unlearn methods that have 
caused you problems. 


In this chapter, we discuss some different approaches to debug- 
ging, talk over the different types of bugs you may find in your 
programs, and suggest some ways to test your program to make 
sure that it works—and keeps on working. 


Let’s begin by looking at where to start when you have a program 
that doesn’t work correctly. 


When things don’t work 


First and foremost, don’t panic! Even the most expert pro- 
grammer seldom writes a program that works the first time. 


To avoid wasting a lot of time on fruitless searches, try to resist 
the temptation to randomly guess where a bug might be. It is 
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better to use a universally tried-and-true approach: divide and 
conquer. 


Make a series of assumptions, testing each one in turn. For 
example, you can say, “The bug must be occurring before function 
xyz is called,” and then test your assumption by stopping your 
program at the call to xyz, to see if there’s a problem. If you do 
discover a problem at this point, you can make a new assumption 
that the problem occurs even earlier in your program. 


If, on the other hand, everything looks fine at function xyz, your 
initial assumption was wrong. You must now modify that 
assumption to “The bug is occurring sometime after function xyz 
is called.” By performing a series of tests like this, you can soon 
find the area of code that is causing the problem. 


That's all very well, you say, but how do I determine whether my 
program is behaving correctly when I stop it to take a look? One 
of the best ways of checking your program’s behavior is to 
examine the values of program variables and data objects. For 
example, if you have a routine that clears an array, you can check 
its operation by stopping the program after the function has 
executed, and then examining each member of the array to make 
sure that it’s cleared. 


Debugging style 
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Everyone has their own style of writing a program, and everyone 
develops their own style of debugging. The debugging sugges- 
tions we give here are just starting points that you can build on to 
mold your own personal approach. 


Many times, the intended use of a program influences the 
approach you take to debug it. Ifa program is for your own use or 
will only be used once or twice to perform a specific task, a full- 
scale testing of all its components is probably a waste of time, 
particularly if you can determine that it is working correctly by 
inspecting its output. If a program is to be distributed to other 
people or performs a task of which the accuracy is hard to 
determine by inspection, your testing must be far more rigorous. 
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Run the whole 


thing Fora simple or throwaway program, the best approach is often 
just to run it and “see what happens.” If your test case has 
problems, run the program with the simplest possible input and 
check the output. You can then move on to testing more compli- 
cated input cases until the output is wrong. This will give youa 
good feeling for just how much or how little of the program is 
working. 


Incremental 


testing When you want to be very sure that a program is healthy, you 
must test the individual routines, as well as checking that the 
program works as expected for some test input data. You can do 
this in a couple of ways: You can test each routine as you write it 
by making it part of a test program that calls it with test data. Or 
you can use Turbo Debugger to step through the execution of 
each routine when the whole program is finished. 


Types of bugs 


Bugs fall into two broad categories: those peculiar to the language 
you’re working in (C, Pascal, or assembler), and those that are 
common to any programming language or environment. 


By making mental notes as you debug your programs, you learn 
both the language-specific constructs you have trouble with, and 
also the more general programming errors you make. You can 
then use this knowledge to avoid making the same mistakes in 
the future, and to give you a good starting point for debugging 
future programs. 


Understanding that each bug is an instance of a general family of 
bugs or misunderstandings will improve your ability to write 
errorless code. After all, it’s better to write bug-free code than to 
be really good at finding bugs. 
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General bugs 


Hidden effects 


Assuming initialized 
data 


Not cleaning up 


The following examples barely scratch the surface of the kinds of 
problems you can encounter in your programs. 


If you are careless about using global variables in functions, a call 
to a function can leave unexpected contents in a variable or data 
structure: 


char workbuf[20]; 

strcpy (workbuf,"all done\n"); 
convert ("xyz"); 

printf (workbuf) ; 


convert (char *p) 

{ 
strcpy(workbuf, p); 
while (*p) 


} 


Here, the correct thing to do would be to have the function use its 
own private work buffer. 


Don’t assume that another routine has already set a variable for 
you: 


char *workbuf; 
addworkstring(char *s) 
{ 
strcpy(workbuf, s); /* oops */ 
} 


You should code a routine of this sort defensively by adding the 
statement 


if (workbuf == 0) workbuf = (char *)malloc(20); 


This sort of bug can crash your program by exhausting heap 
space: 
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Fencepost errors 


C-specific bugs 


Using uninitialized auto- 
variables 


crunch string(char *p) 

{ 
char *work = (char *)malloc(strlen(p)); 
strcpy{work, p); 


return (p); /* whoops--work still allocated */ 


} 


These bugs are named after the old brain teaser that goes “If I 
want to put up a 100-foot fence with posts every 10 feet, how 
many fenceposts do I need?” A quick but wrong answer is ten 
(what about the final post at the far end?). Here’s a simple 
example from the world of C programming: 


for (n = 1; n < 10; nt+) 
{ 

/* oops--only 9 times */ 
} 


Here you can easily see the numbers 1 and 10, and you think that 
your loop goes from one to ten. (Better make that < into a <=.) 


The Turbo C User’s Guide has a section on pitfalls in C program- 
ming. However, this lesson on how to debug is a good place to 
reiterate those pitfalls and expand on them. 


The Turbo C compiler is very good at finding C-specific bugs that 
other compilers don’t warn you about. You can save yourself 
some debugging time by turning on all the warnings that the 
compiler is capable of generating. (See the Turbo C User's Guide for 
information on setting these warnings.) 


What follows is by no means an exhaustive list of ways you can 
get in trouble with C. For some of these errors, the Turbo C 
compiler issues a warning message. Remember to examine the 
cause of any warning messages; they may be telling you about a 
bug in the making. 


In C, an autovariable declared inside a function is undefined until 
you assign a value to it: 


do_ten_times() 
{ 
int n; 
while (n < 10) { 
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Confusing = and == 


Confusing operator 
precedence 


Bad pointer arithmetic 
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nt+t+; 


This function executes the while loop an unpredictable number of 
times because n is not initialized to 0 before being used as a 
counter. 


C lets you both assign a value (=) and test for equality (==) within 
an expression; for example, 


if (x = y) { 
} 


This inadvertently loads y into x and performs the statements in 
the if expression if the value of y is not 0. You almost certainly 
meant to say 


if { == y) 


C has so many operators that it is hard to remember which ones 
are applied first when an expression is evaluated. One combi- 
nation that often causes grief is the mixture of shift operators with 
addition or subtraction. For example, 


x=3<<lH4il 


evaluates to 12, not 7, as you might expect if << took effect before 
the +. 


When you use a pointer to step through an array, be careful how 
you increment and decrement it. For example, 


int *intp; 

intp += sizeof (int); 
does not increment intp to point to the next element of an integer 
array. Instead, intp is advanced by two array elements because in 
adding to or subtracting from a pointer, C takes into account the 
size of the item the pointer is pointing to. All you have to do to 
move the pointer to the next element is 


intpt+ 
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Unexpected sign 
extension 


Unexpected truncation 


Misplaced semicolons 


Be careful about assigning between integers of different sizes: 


int i = OXFFFE; 

long 1; 

l= i; 

if (1 & 0X80000000) { 
ar /* this DOES get executed */ 

} 


One of C’s strong points can cause you trouble if you are not 
aware of how it operates. C lets you assign freely between scalar 
values (char, Int, and so on). When you copy an integer scalar into 
a larger scalar, the sign (positive or negative) is preserved in the 
larger scalar by propagating the sign (highest) bit throughout the 
high portion of the larger scalar. For example, an int value of —-2 
(Oxfffe) becomes a long value of —2 (Oxfffffffe). 


This problem is the opposite of the previous one: 


int i; 
long 1 = 0X10000; 
i=]; 


while {i > 0) { 
xe /* this does NOT get executed */ 
} 


Here, the assignment of | to i resulted in the top 16 bits of | being 
truncated, leaving a value of zero in i. 


The following code fragment may appear to be fine at first glance: 


for (x = 0; x < 10; xtt); 
{ 


/* only executed once */ 


} 


Why does the code between the braces execute only once? Closer 
inspection reveals a semicolon (;) at the end of the for expression. 
This hard-to-find bug causes the loop to execute ten times, but 
does nothing. The subsequent block is then executed once. This is 
a nasty problem because you can’t find it with the usual technique 
of examining the formatting and indenting of code blocks in your 


program. 
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Macros with side The following problem is enough to make you swear off #define 
effects macros for life: 


#define toupper(c) 'a’<= (c)&&(c)<=!2! 2? (c)-'al-"A'l : (c) 
char c, *p; 
c = toupper (*ptt); 


Here, p is incremented two or three times, depending on whether 
the character is uppercase. This type of problem is very hard to 
find, because the side effect is hidden within the macro definition. 


Repeated Another hard one to find: 


autovariable names 
myfunc () 


{ 
int n; 
for (n = 5; n >= 0; n--) 
{ 
int n = 10; 


/* never gets executed */ 


Here, the autovariable name n is reused in an inner block, hiding 
access to the one declared in the outer block. You must be careful 
about reusing variable names in this manner. You can get into 
trouble more easily than you might think, especially if you use a 
limited number of variable names for local loop counters (for 
example, i, n, and so forth). 


Misuse of autovariables This function means to return a pointer to the result: 


int *divide by 3(int n) 
{ 

int i; 

i=n/ 3; 

return (&i); 


} 


The trouble is that by the time the function returns, the auto- 
variable is no longer valid and is likely to have been overwritten 
by other stack data. 
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Undefined function If you don’t end a function with the return keyword followed by 
return value an expression, it returns an indeterminate value; for example, 


char *first capital letter(char *p) 
{ 
while (*p) 
{ 
if (‘Al <= *p && tp <= '2') 
return (p); 
ptt; 
} 


/* Oops--nothing returned here */ 
} 


If there are no capital letters in the string, a garbage value is 
returned. You should puta return(0) as the last line of this 
function. 


Misuse of break The break keyword exits from only a single level of do, for, 
keyword _ switch, or while loops: 


fOr. (ze) 
{ 
while (...) { 
EE. fee) 
break; /* we want to exit for loop */ 


} 


Here, the break exits only from the while loop. This is one of the 
few cases where it is excusable to use the goto statement. 


Code has no effect Sometimes a typo results in perfectly compilable source code. 
However, it probably doesn’t do what you want it to, and it may 
not do anything at all: 


a+b; 


Here, the intended line of code was a += b. 


Pascal-specific 


bugs Because of the strong type- and error-checking features of Pascal, 
there are few bugs specific to the language itself. However, 
because Turbo Pascal gives you the power to turn off much of that 
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error checking, you can introduce errors that you might not have 
otherwise. And even with Pascal, there are ways of getting into 
trouble. 


Uninitialized variables Turbo Pascal does not initialize variables for you; you must do it 
yourself, either through assignment statements or by declaring 
them as typed constants. Consider the following program: 


program Test; 
var 
I,J,Count : Integer; 
begin 
for I := 1 to Count do begin 
J 3= I*]; 
Writeln(I:2,’ ',J3:4) 
end 
end. 


Count has whatever random value occupied its location in 
memory when it was created, so you have no idea how many 
times this loop is going to execute. 


Furthermore, variables declared within a procedure or function 
are created each time you enter that routine and destroyed when 
you exit; you cannot count on those variables retaining their 
values between calls to that routine. 


Dangling pointers Three common errors occur with pointers. The first is using them 
before you have assigned them a value (nil or otherwise). Just like 
any other variable or data structure, a pointer is not automatically 
initialized just by being declared. It should be explicitly set to an 
initial value (by passing it to New or assigning it nil) as soon as 
possible. 


Second, don’t reference a nil pointer, that is, don’t try to access the 
data type or structure that the pointer points to if the pointer itself 
is nil. For example, suppose you have a linear linked list of 
records, and you want to search it for a record with a given value. 
Your code might look like this: 
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function FindNode(Head : NodePtr; KeyVal : Integer) : NodePtr; 


var 
Temp : NodePtr; 
begin 
Temp := Head; 


while (Temp*.KeyVal <> Val) and (Temp <> nil) do 
Temp := Temp*.Next; 
FindNode := Temp 
end; { of function FindNode } 


If Val isn’t equal to the Key field in any of the nodes in the linked 
list, this code tries to evaluate Temp*. Key when Temp is nil, 
resulting in unpredictable behavior. Solution? Rewrite the 
expression to read 


while (Temp <> nil) and (Temp*.Key <> Val) 


and enable short-circuit Boolean evaluation, using the Turbo 
Pascal {$B-} option or the Options | Compiler | Boolean command. 
That way, if Temp does equal nil, the second term is never 
evaluated. 


Finally, don’t assume that a pointer is set to nil just because you've 
passed it to Dispose or FreeMem. The pointer still has its original 
value; however, the memory it points to is now free to be used for 
other dynamic variables. You should explicitly set a pointer to nil 
after disposing of its data structure. 


scope confusion Pascal lets you nest procedures and function very deep, and each 
of those procedures and functions can have its own declarations. 
Consider the following program: 


program Confused; 
var: 
A,B,T : Integer; 


procedure Swap(var A,B : Integer); 


var 
T : Integer; 
begin 
Writeln(/2: A,B,T = ',A:3,B:3,' ',T); 
T := A; 
A := B; 
B := T; 
Writeln(’3: A,B,T = ',A:3,B:3,’ ',T) 
end; { of procedure Swap } 


begin { main body of Confused } 
A := 10; B := 20; T := 30; 
Writeln(’1: A,B,T = ',A:3,B:3,' ',T); 
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Superfluous semicolons 
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Swap (B,A); 
Writeln(’4: A,B,T = ',A:3,B:3,' ',T); 
end. { of program Confused } 


What's the output of this program? It will look something like 
this: 


1: A,B,T = 10 20 30 
2: A,B,T = 20 10 22161 
3: A,B,T = 10 20 20 
4: A,B,T = 20 10 30 


What's happening here is that you have two versions each of A, B, 
and T. The global versions are used in the main body of the pro- 
gram, while Swap has versions local to itself—its formal 
parameters A and B, and its local variable T. To further confuse 
things, we made the call Swap(B,A), which means that the formal 
parameter A is actually the global variable B and vice versa. And, 
of course, there is no correlation between the local and global 
versions of T. 


There was no real “bug” here, but problems can arise when you 
think that you’re modifying something that you aren’t. For 
example, the variable T in the main body didn’t get changed, even 
though you thought it might have. This is the opposite of the 
“hidden effects” bug mentioned on page 214. 


If you also had the following record declaration, things could get 
even more confusing: 


type 
RecType = record 
A,B : Integer; 
end; 
var 
A,B : Integer; 
Rec : RecType; 


Inside a with statement, a reference to A or B would reference the 
fields, not the variables. 


Like C, Pascal allows a “null” statement (one consisting only of a 
semicolon). Placed at the wrong spot, this can create all kinds of 
problems. Consider the following program: 
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program Test; 


var 
I,J : Integer; 
begin 
for I := 1 to 20 do; 
begin 
J:s= I * J; 
Writeln(I:2,’ ',d:4) 
end; 
Writeln(’All done!’) 
end, 


The output of this program is not a list of the first 20 integers and 
their squares; it’s simply 


20 400 
All done! 


That’s because the statement for I := 1 to 20 do; ends witha 
semicolon. This means it executes the null statement 20 times. 
After that, the statements in the begin..end block are executed, the 
final Writeln statement. To fix this, just eliminate the semicolon 
following the do keyword. 


Undefined function If you write a function, you must be sure that the function name 
return value — has some value assigned to it before you exit the function. 
Consider the following section of code: 


const 
NIMax = 100; 
type 
NumList = array[1..NLMax] of Integer; 


function FindMax(List : NumList; Count : Integer) : Integer; 
var 
I,Max : Integer; 
begin 
Max := List(1]; 
for I := 2 to Count do 
if List{I] > Max then 
begin 
Max := List[I]; 
FindMax := Max 
end 
end; { of function FindMax } 


This function works fine—as long as the highest value in List isn’t 
in List[1]. In that case, FindMax never gets assigned a value. A 
correct version of the function would use this: 
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begin 
Max := List[1]; 
for I := 2 to Count do 
4f List[I] > Max then 
Max := List[I]; 
FindMax := Max 
end; { of function FindMax } 


Decrementing Word or Be careful not to decrement an unsigned scalar (Byte or Word) 
Byte variables while testing for >= 0. The following code produces an infinite 


loop: 
var 
wo: Word; 
begin 
woi= 5; 
while w >= 0 do 
wi=wo-dl; 
end. 


After the fifth iteration, w equals 0. The next time through, it’s 
decremented to 65,535 (because words range from 0 to 65,535), 
which is still >= 0. You should use an Integer or Longint in such 
cases. 


Ignoring boundary or Note that both versions of the function FindMax in the previous 
special cases section assume that Count >= 1. However, there may be times 
when Count = 0; that is, the list is empty. If you call FindMax in 
that situation, it returns whatever happens to be in Lis#[1]. Like- 
wise, if Count > NLMax, you'll end up either generating a run- 
time error (if range-checking is enabled) or searching through 
memory locations not contained in List for the maximum value. 


There are two possible solutions to this. One, of course, is never to 
call FindMax unless Count is in the range 1..NLMax. This isn’t a 
flip comment; a serious part of good software design is to define 
the requirements for calling a given routine, then ensuring they 
are met each time that routine is called. 


The other solution is to test Count and return some predetermined 
value if it isn’t in the range 1..NLMax. For example, you might 
rewrite the body of FindMax to look like this: 
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begin 

4£ (Count < 1) or (Count > NLMax) then 
Max := -32768 

else 

begin 
Max := List[1]; 
for I := 2 to Count do 

4£ List[I] > Max then 


Max := List [I] 
end; 
FindMax := Max 
end; {( of function FindMax } 


This leads to the next type of Pascal pitfall: range errors. 


Range errors Turbo Pascal has range-checking turned off by default. This 
produces faster, more compact code, but it also lets you commit 
certain types of errors, such as assigning to variables values 
outside their allowed range or indexing nonexistent elements in 
arrays as shown in the previous example. 


The first step in finding such errors is to turn range-checking back 
on by inserting the {$R+} compiler option into your program, 
compiling the program, and running it again. If you know (or 
suspect) where the error is, you can put this directive above that 
section and add a corresponding {$R-} directive afterward, thus 
enabling range-checking for that section only. If a range error 
does occur, your program stops with a run-time error, and Turbo 
Pascal shows you where the error occurred. 


One common type of range error happens when you are indexing 
through an array using a while or repeat loop. For example, 
suppose you are looking for an array element containing a certain 
value. You want to stop when you've found it or when you reach 
the end of the array. If you've found it, you want to return the 
index of the element; otherwise, you want to return 0. Your first 
effort might look like this: 


function FindVal (List : NumList; Count,Val : Integer) : Integer; 
var 
I: Integer; 
begin 
FindVal := 0; 
I eae Ors 
while (I <= Count) and (List{I] <> Val) do 
Inc (I); 
if I <= Count then 
FindVal := I 


Chapter 14, How to debug a program 225 


Assembler- 
specific bugs 


Forgetting to return to 
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DOS 


Forgetting a RET 
instruction 


end; { of function FindVal } 


This is all very nice, but it could result in a run-time error if Val 
isn’t in List, and you’re using normal Boolean evaluation. Why? 
Because the last time the test is made at the top of the while loop, I 
equals Count+1. If Count = NLMax, you’re beyond the limits for 
List. 


There are two solutions to this type of problem. One is to turn off 
range-checking. However, that could end up introducing subtle 
bugs, especially if the code involved actually changes values. A 
better solution, shown earlier, is to select short-circuit Boolean 
evaluation, either by using the Options | Compiler! Boolean 
command or by using the {$B-} directive. That way, if I > Count, 
the expression 


List[I] <> Val 


is never evaluated. 


Here are some of the common pitfalls of assembly language pro- 
gramming. You should refer to the Turbo Assembler User’s Guide 
for a fuller explanation on these oft-encountered errors—and tips 
on how to avoid them. 


In Pascal, C, and other languages, a program ends automatically 
and returns to DOS when there is no more code to execute, even if 
no explicit termination command was written into the program. 
Not so in assembly language, where only those actions that you 
explicitly request are performed. When you run a program that 
has no command to return to DOS, execution simply continues 
right past the end of the program's code and into whatever code 
happens to be in the adjacent memory. 


The proper invocation of a subroutine consists of a call to the 
subroutine from another section of code, execution of the 
subroutine, and a return from the subroutine to the calling code. 
Remember to insert a RET instruction in each subroutine, so that 
the RETurn to the calling code occurs. When you’re typing a pro- 
gram, it’s easy to skip a RET and end up with an error. 
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Generating the wrong The PROC directive has two effects. First, it defines a name by 
type of return whicha procedure can be called. Second, it controls whether the 
procedure is a near or far procedure. 


The RET instructions in a procedure should match the type of the 
procedure, shouldn’t they? 


Yes and no. The problem is that it’s possible and often desirable to 
group several subroutines in the same procedure. Since these 
subroutines lack an associated PROC directive, their RET instruc- 
tions take on the type of the overall procedure, which is not 
necessarily the correct type for the individual subroutines. 


Reversing operands To many people, the order of instruction operands in 8086 
assembly language seems backward (and there is certainly some 
justification for this viewpoint). If the line 


mov ax,bx 


meant “move AX to BX,” the line would scan smoothly from left 
to right, and this is exactly the way in which many micro- 
processor manufacturers have designed their assembly languages. 
However, Intel took a different approach with 8086 assembly 
language; for us, the line means “move BX to AX,” and that can 
sometimes cause confusion. 


Forgetting the stack or In most cases, you are treading on thin ice if you don’t explicitly 
reserving a too-small allocate space for a stack. Programs without an allocated stack 
stack sometimes run, but there is no assurance that these programs will 
run under all circumstances. Most programs should have a 
-STACK directive to reserve space for the stack, and for each pro- 
gram that directive should reserve more than enough space for 
the deepest stack you can conceive of the program using. 


Calling a subroutine When you’re writing assembler code, it’s easy to think of the 
that wipes out registers _ registers as local variables, dedicated to the use of the procedure 
you’re working on at the moment. In particular, there’s a tendency 
to assume that registers are unchanged by calls to other 
procedures. It just isn’t so—the registers are global variables, and 
each procedure can preserve or destroy any or all registers. 
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The profusion of conditional jumps in assembly language (JE, 
JNE, JC, JNC, JA, JB, JG, and so on) allows tremendous flexibility 
in writing code—and also makes it easy to select the wrong jump 
for a given purpose. Moreover, since condition-handling in 
assembly language requires at least two separate lines, one for the 
comparison and one for the conditional jump (it requires many 
more lines for complex conditions), assembly language 
condition-handling is less intuitive and more prone to errors than 
condition-handling in C and Pascal. | 


String instructions have a curious property: After they’re exe- 
cuted, the pointers they use wind up pointing to an address 1 byte 
away (or 2 bytes for a word instruction) from the last address 
processed. This can cause some confusion with repeated string 
instructions, especially REP SCAS and REP CMPS. 


Any repeated string instruction executed with CX equal to zero 
does nothing. Period. This can be convenient in that there’s no 
need to check for the zero case before executing a repeated string 
instruction; on the other hand, there’s no way to access every byte 
in a segment with a byte-sized string instruction. 


When a string instruction is executed, its associated pointer or 
pointers—S]I or DI or both—increment or decrement. It all 
depends on the state of the direction flag. 


The direction flag can be cleared with CLD to cause string 
instructions to increment (count up) and can be set with STD to 
cause string instructions to decrement (count down). Once cleared 
or set, the direction flag stays in the same state until either 
another CLD or STD is executed, or until the flags are popped 
from the stack with POPF or IRET. While it’s handy to be able to 
program the direction flag once and then execute a series of string 
instructions that all operate in the same direction, the direction 
flag can also be responsible for intermittent and hard-to-find bugs 
by causing the behavior of string instructions to depend on code 
that executed much earlier. 
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Using the wrong sense 
for a repeated string 
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segment defaults 
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operand(s) to a string 
instruction 


Wiping out a register 
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The CMPS instruction compares two areas of memory; the SCAS 
instruction compares the accumulator to an area of memory. 
Prefixed by REPE, either of these instructions can perform a 
comparison until either CX becomes zero or a not-equal 
comparison occurs. Unfortunately, it’s easy to become confused 
about which of the REP prefixes does what. 


Each of the string instructions defaults to using a source segment 
(if any) of DS, and a destination segment (if any) of ES. It’s easy to 
forget this and try to perform, say, a STOSB to the data segment, 
since that’s where all the data you're processing with nonstring 
instructions normally resides. 


In general, it’s desirable to use the largest possible data size 
(usually word, but dword on an 80386) for a string instruction, 
since string instructions with larger data sizes often run faster. 


There are a couple of potential pitfalls here. First, the conversion 
from a byte count to a word count by a simple 


shr cx,l 


loses a byte if CX is odd, since the least-significant bit is shifted 
out. 


Second, make sure you remember SHR divides the byte count by 
two. Using, say, STOSW with a byte rather than a word count can 
wipe out other data and cause problems of all sorts. 


String instructions with multiple prefixes are error-prone and 
should generally be avoided. 


The optional operand or operands to a string instruction are used 
for data sizing and segment overrides only, and do not guarantee 
that the memory location referenced is accessed. 


Multiplication—whether 8 bit by 8 bit, 16 bit by 16 bit, or 32 bit by 
32 bit—always destroys the contents of at least one register other 
than the portion of the accumulator used as a source operand. 
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The string instructions, MOVS, STOS, LODS, CMPS, and SCAS, 
can affect several of the flags and as many as three registers 
during execution of a single instruction. When you use string 
instructions, remember that SI, DI, or both either increment or 
decrement (depending on the state of the direction flag) on each 
execution of a string instruction. CX is also decremented at least 
once, and possibly as far as zero, each time a string instruction 
with a REP prefix is used. 


While some instructions affect registers or flags unexpectedly, 
other instructions don’t even affect all the flags you might expect 
them to. 


Flags last only until the next instruction that alters them, which is 
usually not very long. It’s a good practice to act on flags as soon as 
possible after they’re set, thereby avoiding all sorts of potential 
bugs. 


An assembler program may refer either to the offset of a memory 
variable or to the value stored in that memory variable. 
Unfortunately, assembly language is neither strict nor intuitive 
about the ways in which these two types of references can be 
made, and as a result, offset and value references to a memory 
variable are often confused. 


One of the most difficult aspects of programming the 8086 is that 
memory isn’t accessible as one long array of bytes, but is rather 
made available in chunks of 64K relative to segment registers. 
Segments can introduce subtle bugs; if a program attempts to 
access an address past the end of a segment, it actually ends up 
wrapping back to access the start of that segment instead. 


Every interrupt handler should explicitly preserve the contents of 
all registers. While it is valid to preserve explicitly only those 
registers that the handler modifies, it’s good insurance just to 
push all registers on entry to an interrupt handler and pop all 
registers on exit. 
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Forgetting group 
overrides in operands 
and data tables 


Segment groups let you partition data logically into a number of 
areas without having to load a segment register every time you 
want to switch from one of those logical data areas to another. 


Unfortunately, there are a few problems with the way the 
Microsoft Macro Assembler (MASM) handles segment groups, so 
until Turbo Assembler came along, segment groups were quite a 
nuisance in assembler. They were, however, an unavoidable 
nuisance, for they are required in order to link assembler code to 
high-level languages such as C. 


In MASM Quirks mode, Turbo Assembler emulates MASM, warts 
and all. This means that in MASM Quirks mode, Turbo 
Assembler has the same problems with segment groups that 
MASM has. If you’re not planning to use MASM Quirks mode, 
read no more, but if you are going to use MASM Quirks mode, 
refer to the Turbo Assembler User’s Guide for more information. 


Accuracy testing 


Testing boundary 
conditions 


Invalid data input 


Making a program work with valid input is only part of the job of 
testing. The following sections discuss some important test cases 
that any program or routine should be subjected to before being 
given a clean bill of health. 


Once you think a routine works with a range of data values, you 
should subject it to data at the limits of the range of valid input. 
For example, if you have a routine to display a list from 1 to 20 
items long, you should make sure it behaves correctly both when 
there is exactly 1 item and exactly 20 items in the list. This can 
flush out the one-too- few and one-too-many “fencepost” errors 
(described on page 215). 


Once you are sure that a routine works with a full range of valid 
input, check that it behaves correctly when it’s given invalid 
input. Check that erroneous input is rejected, even when it’s very 
close to valid data. For example, the previous routine that 
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accepted values from 1 to 20 should make sure that 0 and 21 are 
rejected. 


Empty data input 
This is a frequently overlooked area, both in testing and in 
designing a program. If you write a program to have reasonable 
default behavior when some input is omitted, you greatly 
enhance its ease of use. 


Debugging as part of program design 


When you first start designing your program, you can plan for the 
debugging phase. One of the most basic tradeoffs in program 
design involves the degree to which the different parts of your 
program check that they are getting valid input and that their 
output is reasonable. 


If you do a lot of checking, you end up with a very resilient pro- 
gram that can often tell you about an error condition but 
continues to run after performing some reasonable recovery. You 
also end up with a larger and slower program. This type of pro- 
gram can be fairly easy to debug because the routines themselves 
inform you of invalid data before the dangers can be propagated. 


You can also implement a program whose routines do little or no 
validation of input or output data. Your program will be smaller 
and faster, but bad input data or a small bug can bring things to a 
grinding halt. This type of program can be the most difficult to 
debug, since a small problem can end up manifesting itself much 
later during execution. This makes it hard to track down the 
original error. 


Most programs end up being a mixture of these two techniques. 
You should treat input from external sources (such as the user or 
a disk file) with greater suspicion than data from one internal 
routine calling another. 


The sample debugging session 


This sample session uses some of the techniques we talked about 
in the previous sections. The program you are debugging is a 
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version of the demonstration program used in Chapter 3 
(TCDEMO.C or TPDEMO.PAS), except this one has some 
deliberate bugs in it. 


Make sure that your current directory contains the two files 
needed for the debugging demonstration. If you’re a C program- 
mer, you'll need TCDEMOB.C and TCDEMOB.EXE. If you’re 
debugging a Pascal program, you'll need TPDEMOB.PAS and 
TPDEMOB.EXE. (The B in these file names stands for “buggy.”) 


Go ahead and compile the source code program to generate your 
-EXE file. (If you are compiling TCDEMOB.C, open it in the 
integrated development environment and set the Options | 
Compiler | Optimization | Use Register Variables switch to Off 
before you compile.) 


C debugging session 


Looking for errors 


This section uses a Turbo C program as its example. If you’re a 
Pascal programmer, refer to page 238 for the sample debugging 
session using a Turbo Pascal program. 


Before we start the debugging session, let’s run the buggy demo 
program to see what’s wrong with it. To start the program, type 


TCDEMOB 
You are prompted for lines of text. Enter two lines of text 


one two three 
four five six 


A final empty line ends your input. TCDEMOB then prints out its 
analysis of your input: | 


Arguments: 

Enter a line (empty line to end): one two three 
Enter a line (empty line to end): four five six 
Enter a line (empty line to end): 

Total number of letters = 7 

Total number of lines = 6 

Total word count = 2 

Average number of words per line = 0.3333333 
‘E’ occurs 1 times, 0 times at start of a word 
‘FE’ occurs 1 times, 1 times at start of a word 
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Deciding your 
plan of attack 


Starting Turbo 
Debugger 


'N’ occurs 1 times, 0 times at start of a word 
‘QO’ occurs 2 times, 1 times at start of a word 
‘R’ occurs 1 times, 0 times at start of a word 
‘'U’! occurs 1 times, 0 times at start of a word 
There is 1 word 3 characters long 
There is 1 word 4 characters long 


Notice there are erroneous numbers for the total number of 
words, letters, and word count. Later on, the letter and word 
frequency tables seem to be based on an erroneous letter and 
word count. This is an all-too-typical situation—the program 
must have more than one thing wrong. This happens frequently 
in the early stages of debugging a program. 


Your first task is to decide which problem to attack first. A good 
rule of thumb is to start with the problem that appears to be 
happening “first.” In this program, each input line is broken 
down into words, then analyzed, and finally, after all the lines 
have been entered, the tables are displayed. Since the word and 
letter counts are off as well as the tables, it’s a good bet that 
something is wrong during the initial breaking down and 
counting phase. 


Now is the time to start debugging, after you've thought about the 
problem for a moment and decided on a rough plan of attack. 
Here, the strategy is to examine the routine makeintowords, to see if 
it is correctly chopping the line into null-terminated words, and 
then see if analyzewords is correctly counting the analyzed line. 


To start the debugging session, type 
TD TCDEMOB 


Turbo Debugger loads the buggy demo program and then 
displays its startup screen. If you wish to exit from the tutorial 
session and return to DOS, press Alt-X at any time. If you get 
hopelessly lost, you can reload the demonstration program at any 
time and start at the beginning by pressing Ctrl-F2. (Note that this 
doesn’t clear breakpoints or watches.) 


Since the first thing you want to do is to check that makeintowords 
is working correctly, run the program up to that routine and then 
check it. There are two approaches you can use: Either step 
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through makeintowords as it executes, making sure that it does the 
right thing, or stop the program after makeintowords has done its 
stuff and see if it did the right thing. 


Since makeintowords has a clearly defined task and it’s easy to 
determine whether it’s working correctly by inspecting the output 
buffer it produces, let’s opt for the second approach. To do this, 
move down to line 42 and press F4 to run to this line. When the 


program screen appears, type 
one two three 


and press the Enter key. 


Inspecting 


You are now stopped at the source line after the call to 
makeintowords. Look at the contents of buffer to see if the right 
thing happened. Move the cursor up a line, place it under the 
word buffer, and press Alt-F10 | (for Inspector) to open an Inspector 
window to show the contents of buffer. Use the arrow keys to 
scroll through the elements in the array. Notice that makeintowords 
has indeed put a single null character (0) at the end of each word 
as it is meant to. This means that you should execute more of the 
program and see if analyzewords is doing the right thing. First, 
remove the Inspector window by pressing Esc. Then, press F7 
twice to execute to the start of analyzewords. 


Breakpoints 


Check that analyzewords has been called with the correct pointer to 
the buffer by moving the cursor under bufp and pressing Alt-F10 I. 
You can see that bufp indeed points to the null-terminated string 
‘one’. Press Esc to remove the Inspector window. Since there 
seems to be a problem with counting characters and words, let’s 
put a breakpoint at the places where a character and a word are 
counted: 


1. Move to line 93 and press F2 to set a breakpoint. 
2. Move to line 97 and set another breakpoint. 


3. Finally, set a breakpoint on line 99 so you can look at the 
character count this function returns. 


Setting multiple breakpoints like this is a typical way to learn 
about whether things are happening in the right order in a pro- 
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The Watches 
window 


The Evaluate/ 
Modify dialog 
box 


Eureka! 


gram, and lets you check on important data values each time the 
program stops at a breakpoint. 


Run the program by pressing F9. The program stops when it 
reaches the breakpoint on line 93. Now you want to look at the 
value of charcount. Since you'll want to check it each time you hit 
a breakpoint, this is an ideal time to use the Watch command to 
place it in the Watches window. Move the cursor under charcount 
and press Alf-F10 W. The Watches window at the bottom of the 
screen now displays the current value of 0. To make sure that the 
character is being counted properly, execute a single line by 
pressing F7. The Watches window now shows that charcount is 1. 


Run the program again by pressing F9. You are now back at line 
93 for another character. Press F9 again twice to read the last letter 
on the word and the terminating null. charcount now correctly 
shows 3, and the wordcounts array is about to be updated to count 
a word. Everything is fine so far. Press F9 again to start processing 
the next word in the buffer. AHA! Something is wrong. 


You expected the program to stop again on line 93 as it processed 
the next word, but it didn’t. It went straight to the statement that 
returns from the function. The only way to end up on line 99 is if 
the while loop that started on line 83 no longer has a true test 
value. This means that *bufp != 0 must evaluate to false (that is, 0). 


To check this, move back to line 83 and mark the entire expression 
*bufp != 0 by putting the cursor under the *, pressing Ins, and 
moving the cursor to the final ‘0’ before the ’)’. Now evaluate 
this expression by opening the Data | Evaluate Modify dialog box 
and pressing Enter, and choosing the Eval button to accept the 
marked expression. The value is indeed 0. Press Esc to return to 
the Module window. 


Now here comes the analytical leap that causes you to “solve” the 
bug. The reason bufp points to a 0 is because that is where the 
inner while loop starting on line 86 left it at the end of a word. To 
continue to the next word, you must increment bufp past the 0 
that ended the previous word. To do this, you need to adda 
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“bufpt++” statement before line 97. You could recompile your pro- 
gram with this statement added, but Turbo Debugger lets you 
“splice” in expressions by using a fancy sort of breakpoint. 


To do this, first reload the program by pressing Ctrl-F2so you can 
test with a clean slate. Now remove all the breakpoints you set in 
the previous session by typing Alt-B D. Go back to line 97 and set a 
breakpoint again by pressing F2. Now, open a Breakpoints 
window by pressing Alt-V B. Set this breakpoint to execute the 
expression bufp++ each time it is encountered: 


1. Choose View | Breakpoints. 
2. Open the Breakpoints window local menu by pressing Alf-F10. 


3. Choose Set Options to open the Breakpoint Options dialog 
box. 


. Set the Action radio buttons to Execute. 
. Press Tab to get to the Action Expression prompt. 
. Enter bufptt+. 


. Press Esc to close the dialog box and Alt-F3 to return to the 
Module window. 


NW oO 


Now run the program. Enter the usual two input lines 


one two three 
four five six 


Press Enter at the third prompt, and when the program has 
terminated, press Alt-F5 to look at your output on the User screen. 


You’ll notice that things have improved considerably. The total 
number of words and lines seem to be wrong, but the tables are 
correct. Stop at the beginning of the printstatistics routine and see 
if it is given the correct values to print. First reload the program 
by pressing Ctr-F2 to retest. Then go to line 104 and press F4 to 
execute to there. Move the cursor to the nlines argument and press 
Alt-F10 | to look at its value. Note that the value is 6 where it 
should be 2. 


Now go back to where nlines is called from in main and look at 
the its value there. Move the cursor to line 36, place it under 
nlines, and press Alt-F10 | to look at the value. The value of nlines in 
main is 2, which is correct! If you go down to line 46, you will 
notice that the two arguments nwords and nlines have been 
reversed. There is no way that the compiler could have known 
that you meant to have them the other way around. 
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If you correct these two bugs, the program will run correctly. The 
files TCDEMO.EXE is a corrected version that you may run if you 
are curious. 


Pascal debugging session 


Looking for errors 
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This section uses a Turbo Pascal program as its example. If you’re 
a C programmer, you should look at the preceding section, start- 
ing on page 233, which takes you through a session using a Turbo 
C program. 


Before we start the Pascal debugging session, let’s run the buggy 
Pascal demo program to see what’s wrong with it. The program is 
already compiled and on your distribution disk. 


To start the program, enter the program name and pass it three 
command-line arguments: 


TPDEMOB first second third 


You'll be prompted for lines of text. Enter two lines of text exactly 
as follows: . 


ABC DEF GHI 
abc def ghi 


A final empty line ends your input. TPDEMOB then prints out its 
analysis of your input: 

9 char(s) in 3 word(s) in 2 line(s) 

Average of 0.67 words per line 


Word length: 1 2 3 4 5 6 7 8 9 10 


Frequency: 0 0 3 0 0 0 0 0 0 0 

Letter: M 

Frequency: 21 1 2 232 +2 2 «J J 1 0 0 0 0 
Word starts: 1 0 0 1 0 0 1 0 0 0 0 0 +90 
Letter: Z 

Frequency: 0 0 0 0 0 0 0 0 0 0 0 0 90 


Word starts: 0 0 0 0 0 0 0 0 0 0 0 #90 


Program name: C:\td\tpdemob.exe 
Command line parameters: firs@ second third 
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There are five separate problems with this output: 


1. The number of words is wrong (3 instead of 6). 
2. The number of words per line is wrong (0.67 instead of 3.00). 


3. The column headings for the second and third tables display 
only one letter each (instead of A..M and N..Z). 


4. You typed two lines, each containing a letter from A..I, but the 
letter frequency tables show only a count of one each for those 
letters. 


5. The last character of each command-line parameter entered 
was lost and random characters are being displayed (although 
the last parameter is okay). 


Deciding your 


plan of attack Your first task is to decide which problem to attack first. A good 
rule of thumb is to start with the problem that appears to be 
happening first. In this program, after procedure Init is called to 
initialize data, keyboard input is read by function GetLine and 
then processed by procedure ProcessLine until the user enters an 
empty string. ProcessLine scans each input string and updates the 
global counters. Then, the results are displayed by procedure 
ShowResults. Finally, ina completely independent subprogram, 
procedure ParmsOnHeap builds a linked list of command-line 
parameters on the heap and then traverses and displays that list 
at the end of the program. 


The average number of words per line is computed by 
ShowResults, using the number of lines and words. Since the word 
count seems to be off, take a look at ProcessLine to see how 
NumWords is updated. Even though NumWords is wrong, the 0.67 
words-per-line figure doesn’t make sense. There’s probably an 
error in the ShowResults calculation, which needs your attention as 
well. 


The column titles for all the tables are drawn at the request of 
ShowResults. You should wait until the main loop terminates 
before tracking down the second and third bugs. Since the letter 
and word counts are wrong, it’s a good bet that something is 
amiss inside ProcessLine, and that’s where you should start 
looking for the first and fourth bugs. 
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Starting Turbo 
Debugger 


Moving through 
the program 


Finally, once you've scrutinized the word and letter counting 
parts of the program, take a look at ParmsOnHeap to find and fix 
the last (fifth) bug. 


Now is the time to actually start debugging—after you’ve thought 
about the problem for a moment and decided on a rough plan of 
attack. 


To start the debugging sample session, load the debugger and 
give it the same command-line parameters you gave it earlier: 


TD TPDEMOB first second third 


Turbo Debugger loads the buggy demo program and displays the 
startup screen. If you wish to exit from the tutorial session and 
return to DOS, press Alt-X at any time. If you get hopelessly lost, 
you can always reload the demonstration program and start from 
the beginning again by pressing Cirl-F2. (Note that this doesn’t 
clear breakpoints or watches.) 


There are two approaches to debugging a routine like ProcessLine: 
Either step through it line-by-line as it executes and make sure it 
does the right thing, or stop the program immediately after 
ProcessLine has done its stuff and see if it did the right thing. Since 
both the letter and word counts are wrong, you probably ought to 
look inside ProcessLine carefully and see how characters are 
processed. 


Now you're going to run the program and step inside the call to 
ProcessLine. There are many ways to do that. You can press F8 four 
times (to step over procedure and function calls), then press F7 
once (to trace into the call to ProcessLine). You can also move the 
cursor down to line 231, press F4 (Go to Cursor command), and 
press F7 once to step into ProcessLine. 


There are even more ways to get into ProcessLine. Try this one: 
Press Alt-F9. A dialog box pops up, prompting you to enter a code 
address to run to. Type processline, and press Enter. The program 
will now run until ProcessLine gains control. When you are 
prompted to enter a string, enter the same data as before (that is, 
ABC DEF GHI). 
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ProcessLine contains several loops. An outer one scans the entire 
string. Inside that loop, there’s one loop to skip over non-letters, 
and a second one to process words and letters. Move the cursor to 
the while loop on line 133 and press F4 (Go to Cursor). 


This loop keeps scanning until it reaches the end of the string or 
until it finds a letter. Each character scanned is checked via a call 
to a Boolean function, IsLetter. Press F7 to trace into IsLetter. 
IsLetter is a nested function that takes a character value and 
returns True if it’s a letter; otherwise, False. A not-very-close look 
reveals that it checks only for uppercase letters. It should either 
check for characters in the range A to Z and a to z, or it should 
convert the character to uppercase before performing the test. 


A quick look at both lines of input that you originally entered 
provides a further clue to the source of the bug: You entered both 
uppercase and lowercase letters from A to I, but only the upper- 
case letters entered were displayed in the totals. Now you can see 
why. 


Get back to the line that called IsLetter by another navigation 
technique: Press Alt-F8, which runs past the end statement of the 
current procedure or function. Since the second line of input you 
originally entered, abc def ghi, contained only lowercase letters, 
each character was treated as whitespace and skipped. This 
throws off both the letter counts and the word count, and solves 
the mysteries of bugs #1 and #4. 


Tne Evaluate/ 


Modify dialo By the way, there’s another powerful way to verify IsLetter’s 
y See y P y 
box Misbehavior. Invoke the Evaluate/Modify dialog box by pressing 
Alt-D E and enter the following expression: 


IsLetter (‘a’) = IsLetter (‘A’) 


Aand a are both letters, but the evaluation False confirms that 
they’re not treated the same by IsLetter. (You can use the 
Evaluate/ Modify dialog box and Watches window to evaluate 
expressions, perform assignments, or, as you did here, call proce- 
dures and functions. For more information, refer to Chapter 6.) 
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Inspecting 


Two bugs down, three to go. Bug #2 is much easier to find than 
the previous ones. Press Alt-F8 to exit ProcessLine, then move the 
cursor to line 234 and press F4 to run to the cursor position. 


TPDEMOB prompts you for a string. Type abc def ghi and press 
Enter, then press Enter the second time the prompt appears. Now 
press F7 to step into ShowResults. 


Remember, you're trying to find out why the average number of 
words per line is incorrect. The first line in ShowResults calculates 
the number of lines per word instead of words per line. Clearly, 
those two terms should be reversed. 


As long as you’re here, you might as well make sure that 
NumLines and Num Words have the values you'd expect. NumLines 
should equal 2, and—because of the IsLetter bug you've 
uncovered but haven’t fixed—Num Words should equal 3. Move 
the cursor to NumLines and press Alt-F10 / to inspect a variable. The 
Inspector window shows you NumLines’ address, type, and 
current value in both decimal and hexadecimal. The value is 
indeed equal to 2, so you can move on and have a look at 
NumWords. Press Esc to close the Inspector window, move the 
cursor forward to NumWords, and press Alt-F10 |again (you can 
also use the hot key, Cirl-). Num Words has the expected (incorrect) 
value of 3, so you can move on. 


Or can you? There’s another problem with this calculation, and it’s 
not even on our list. There is no check to see whether the second 
term is 0 before the division is performed. If you run the program 
from the beginning and enter no data at all (just press Enter when 
prompted), the program crashes (even after you reverse the 
divisor and the dividend). 


To confirm this, press Esc to close the Inspector window, type Alt-R 
P to end the current debug session, press F9 to run the program 
from the beginning, and press Enterat TPDEMOB’s string prompt. 
The program terminates and an error box displays a run-time 
error. You should modify this statement to read 


if NumLines <> 0 then 

AvgWords := NumWords / NumLines 
else 

AvgWords := 0; 
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So much for bugs #2 and #2b. As long as you're tinkering with the 
Inspector window, try using it to “walk” through a data structure. 
Move the cursor up to the declaration of LetterTable on line 50. 
Place the cursor on the word LetterTable, and press Alt-F10 I. You 
can see it’s an array of records, 26 elements long. Use the cursor 
keys to scroll through each element of the array, and press Enter to 
step into one of the array elements. This is a very powerful way of 
examining your data structures, and will be especially handy 
when you traverse ParmsOnHeap’s linked list later on. 


Watches 


You've still got to squash that column title bug (#3) in ShowResults. 
Since you already terminated the program when you tracked the 
divide-by-zero error, prepare for another session by pressing Alt- 
R P (to reset the program). Then press Alt-F9, type showresults, and 
press Enter. Now type the all-too-familiar data ABC DEF GHI and 
press Enter again. Finally, type abc def ghi and press Enter twice. 
Turbo Debugger should be stopped at ShowResults. 


ShowResults uses a nested procedure, ShowLetterInfo, to display 
the letter tables. Move the cursor down to line 103, press F4, then 
press F7 to step into ShowLetterInfo. 


There are three for loops. The first one displays the column titles, 
and the second and third display frequency counts. Use F7to step 
to the first loop on line 63. Position the cursor over FromLet and 
ToLet and use Alt-F10 | to check their values. They look okay (the 
first equals A, and the second equals M). Press Alt-F5 to view the 
User screen and see where things stand. Press any key to return to 
the Module window. 


When you’re stepping through a loop like this, the Watches 
window is very handy; position the cursor over ch and press Ct/- 
W. Now use F7 to step through the for loop. As expected, it steps 
down to the Write statement on line 64. If you look at the Watches 
window, though, you'll see that ch’s value is already M. (It already 
executed the entire loop!) There’s an extra semicolon right after 
the keyword do, making the for loop do absolutely nothing 13 
times. When control falls through to the Write statement on line 
64, the current value of ch, M, is output and the program moves 
on. Removing that extra semicolon eliminates bug #3. 
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Just one more 
bug... 


It’s time to track down that strange bug with the command-line 
parameters. To refresh your memory, the last character of all but 
the last command-line parameter was garbage. Perhaps the string 
length byte was wrong, or perhaps the string data was over- 
written by some later assignment. 


Use the Watches window to find out. Press Alf-F9, type parmsonheap 
and press Enter. The for statement loops through all the 
command-line parameters, constructing a linked list and copying 
each string onto the heap as it goes. One pointer, Head, points to 
the beginning of the list; Tail points to the last node in the list; and 
Temp is used as temporary storage to allocate and initialize a new 
node. Since the string data is corrupted, press Ctrl-F7 and add the 
following expression to the Watches window: 


Tail*.Parm* 


This keeps track of the string data stored in the last node in the 
list. Of course, this value will be garbage until Tail is initialized on 
line 207. 


Rather than step through line-by-line, just keep an eye on the 
Watches window at the end of each iteration. Move the cursor to 
line 208 and press F2 to set a breakpoint there. Now press F9 to 
run to that breakpoint. If you’re using DOS 3.x, you'll see the full 
path to TPDEMOB.EXE in the Watches window. (If you're using 
DOS 2.x, you'll see an empty string; in that case, just press F9 
again and then go on.) The string data looks just fine. 


Press F9 to execute the loop another time. Again, the data looks 
okay. Now you know that the string is being copied onto the heap 
correctly. You can use the Inspector window to find out whether 
it’s been corrupted yet. Move the cursor over Head on line 203 and 
press Alt-F10 I. 


Look at the value referenced by Parm by pressing J, followed by 
Enter. You're looking at the first node in the list, and its string data 
is already corrupted. If you press Esc, 1, and then press Enter _ 
again, you'll open an Inspector window onto the second node in 
the list. Press J, followed by Enter, to inspect its string data. It’s 
intact, and, in fact, is the same node referenced by the Tail pointer. 
Something is definitely clobbering the tail end of the string data. 
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Keep your eye on the Watches window while you use F7 to step 
through the loop. The call to GetMem on line 199 is the culprit; 
before that call, Tail4.Parm” is equal to first. Immediately after the 
call to GetMem, the last character in Tail*Parm” is trashed. 


What's happening? For each command-line parameter, the for 
loop allocates first a record, then the string data, then the next 
record, and so on. The GetMem call on line 199 should allocate 
enough for the length of the string plus the length byte, but you 
can see it does not add 1 to Length(s). Though the string assign- 
ment on line 200 succeeds in doing the copy, it actually uses 1 
more byte than was allocated to it. Thus, the last character of the 
string is overlapped by the first byte of the next record allocated 
when a call is made to New(Temp). The last parameter escapes 
unscathed because it’s not followed by another ParmRec. 


Whew. That's all the (known) bugs in this program. Perhaps 
you'll find some more as you step through the code. You can fix 
the bugs (they are marked with two asterisks (**) for your 
convenience) and then recompile; or you can run TPDEMO.PAS, 
the bug-free version of this program, discussed in Chapter 3. 


Chapter 14, How to debug a program 245 


246 Turbo Debugger User's Guide 


Ike) 


Virtual debugging on the 80386 
processor 


Turbo Debugger lets you use the full power of systems that have 
the 80386 processor. Virtual debugging lets the program you’re 
debugging use the full address space below 640K, just as if no 
debugger were loaded. (Turbo Debugger is loaded into extended 
memory, above the 1MB address point.) 


You debug exactly as you would normally use Turbo Debugger, 
except that once the TDH386 device driver is loaded, your 
program loads and runs at exactly the same address whether or 
not it’s being debugged. Virtual debugging is extremely useful 
both for debugging programs that are large, and for finding bugs 
that go away if the program is loaded higher in memory, as it is 
when it is being debugged normally. 


Virtual debugging also lets you watch for reads or writes to arbi- 
trary memory or I/O locations, all at full or nearly full processor 

speed. This gives you some of the power of a hardware debugger 
at no additional cost. 


80286 users! If you have an 80286 processor, you can make more memory 
available than you would normally have with Turbo Debugger by 
using the protected-mode debugger, TD286. See Chapter 16 for 
more information. 
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Equipment required for virtual debugging 


You must have a computer based on the 80386 processor in order 
to use the virtual debugger. You must also have 640K of available 
extended memory. If you have used up your extended memory 
for RAM disks, caches, and so forth, you may want to make a 
special CONFIG.SYS or AUTOEXEC.BAT file that removes some 
of these programs when you want to use virtual debugging. 


Installing the virtual debugger device driver 


Before starting the virtual debugger, you must make sure that you 
have installed its device driver in your CONFIG.SYS file. Do this 
by including a line similar to the following in CONFIG.SYS: 


DEVICE = TDH386.SYS 


If you have placed the TDH386.SYS device driver somewhere 
other than in the root directory, make sure that you include that 
directory path as part of the device driver file name. 


Normally, the virtual debugger lets you have up to 256 bytes of 
DOS environment strings. If this is not enough, or if you don’t 
need that much and would like to conserve as much memory as 
possible, use the -e option in CONFIG.SYS to set the number of 
bytes of environment. For example, 


DEVICE = TDH386.SYS -e2000 


reserves 2000 bytes for your DOS environment variables. 


starting the virtual debugger 
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You start the virtual debugger much as you would normally start 
Turbo Debugger, with a command line like this: 


TD386 [options] program [program options} 


In other words, you simply enter 1D386 instead of TD. TD386 then 
takes care of finding the Turbo Debugger executable program and 
loading it into extended memory. 


If you have other programs or device drivers that use extended 
memory, such as RAM disks, caches, or whatever, you must tell 
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TD386 how much extended memory to set aside for these other 
programs. Do this by using the -e command-line option. Follow 
the -e with the number of kilobytes (K) of extended memory used 
by the other programs. For example, 


TD386 -e512 myprog 


This command line informs TD386 that you want to reserve the 
first 512K of extended memory for other programs. 


t> Normally, if your system supports the XMS standard, it is not 
necessary to inform TD386 how much memory to set aside for 
programs in extended memory; the programs have already 
passed that information to TD386. You need to use -e only with 
programs (such as VDISK) that don’t communicate with the XMS 
standard. 


Since you probably always reserve the same amount of extended 
memory for other programs, TD386 gives you a way to perma- 
nently set the amount of extended memory to reserve. Use the —w 
option with the -e option to specify that you want the -e value to 
be permanently set in the TD386 executable program file. 


You'll then be prompted for the name of the executable program. 
If you are running on DOS 3.0 or later, the prompt indicates the 
path and file name that you executed TD386 from. You can accept 
this name by pressing Enter, or you can enter a new executable file 
name. The new name must already exist and be a copy of the 
TD386 program that you have already made. 


If you are running on version 2.x of DOS, you will have to supply 
the full path and file name of the TD386 executable program. 


Here is a complete list of command-line options for TD386.EXE: 
—?, -h Accesses help on TD386. 


-b Lets you break out of programs with Ctr-Break, 
even when interrupts are disabled. 


—e#i### Specifies the number of kilobytes of extended 
memory being used by other programs or by the 
program you're debugging. (You don’t need this 
option if your system supports the XMS 
standard.) 


—fHHH Enables EMS emulation through paging (in 
extended memory) and sets the page frame 
segment to #### (in hex). The last three digits 
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must be 000 (like C000 or E000). Note that this 
option only applies to Turbo Debugger’s EMS 
calls. If you don’t use this option when you load 
TD386, TD386 will not be able to use EMS. If you 
cannot load your symbol table, try using the —f 
option to force TD386 to borrow from extended 
memory. 


No real EMS: —fD000 
Real EMS at D000: —fE000 
Real EMS at E000: —fD000 


—t- Disables EMS emulation (presumably to override 
a previous command-line option). 
-w Modifies TD386.EXE with the new default value 


of —e or -f. You can enter a new executable file 
name that does not already exist, and TD386 will 
create the new executable file. 


Note that TD386.EXE options must appear first in the 
command line before any Turbo Debugger options or the 
program name. For example, 


TD386 -e1024 -£D000 -w 


reserves 1024K of extended memory, enables EMS 
emulation with a page frame of D000, and modifies 
TD386.EXE with these values. 


For a list of all the command-line options available for 
TD386.EXE, just type 1D386 -? or TD386 -h and press Enter. 


Note: If you have an 80386-based machine and want to read 
the command-line options for TD386.EXE, TDH386.SYS 
must be loaded. 


Differences between normal and virtual 
debugging 


Most things work exactly the same whether you are debug- 
ging normally or using the 80386 virtual debugging 
capability. The following items behave differently: 


g When you use the File | DOS Shell command to run a DOS 
command, the program you're debugging is never 
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swapped to disk. This means you may not always have 
enough memory to run other programs from the DOS 
prompt. 

o Your program can use nearly all of the 80386 instructions, 
with the exception of the privileged protected-mode 
instructions: CLTS, LMSW, LTR, LGDT, LIDT, LLDT. 


o Even though you can use all the 80386 extended address- 
ing modes and 32-bit registers during virtual debugging, 
you can’t access memory above the 1MB point. If you try 
to do so, an exception interrupt will be generated, and 
Turbo Debugger will regain control. 

o You can’t use virtual debugging if you’re already running 
a program or device driver that uses the virtual and 
protected modes of the 80386 processor. This includes pro- 
grams such as: 


e DesqView operating environment 

o Microsoft Windows-386 operating environment 
o QEMM:SYS, the QuarterDeck EMS simulator 

0 CEMM.SYS Compaq EMS simulator 

0 386*MAX 


If you normally use one of these or similar programs, you 
will have to stop them or unload them before using 
TD386. 


o If you are using virtual debugging, TD386 can catch 
exceptions generated by your program. If an exception 
occurs, your program stops, and TD386 reports the 
exception that occured. The error message that appears 
indicates the nature of the exceptions, and the arrow in 
the CPU window Code pane—or the cursor in the Module 
window—marks the instruction that caused the 
exception. 


0 You should not get an unexpected interrupt. If you do, 
contact Borland technical support. 


TD386 error messages 


TD386 generates one of the following messages when it 
can’t start, and then returns to the DOS prompt. You must 


Chapter 15, Virtual debugging on the 80386 processor 


251 


correct the condition before you can start TD386 
successfully. 


TD386 error: 80386 device driver missing or wrong version 
You must install the TDH386.SYS device driver in your 
CONFIG:SYS file before you invoke TD386 from the DOS 
command line. 

TD386 error: Can't enable the A20 address line 

TD386 can’t access the memory above 1MB. This may 
happen if you’re running on a system that is not exactly IBM 
compatible. 


TD386 error: Can’t find TD.EXE 
TD386 could not find TD.EXE. 


TD386 error: Couldn’t execute TD.EXE 
TD386 could not run TD.EXE. 


TD386 error: Environment too long; use —e### switch with 
TDH386.SYS 
You need to change the -e option as described on page 248. 


TD386 error: Not enough Extended Memory available 
TD386 ran out of memory. You need to get more memory 
for your machine or free up memory (by reducing a RAM 
disk, for example). 


TD386 error: Wrong CPU type (not an 80386) 
You are not running on a system with an 80386 processor. 


The following errors might occur if you’re trying to modify 
TD386 with the —-w option: 


TD386 error: Cannot open program file 
TD386 error: Cannot read program file 
TD386 error: Cannot write program file 


TD386 error: Program file corrupted or wrong version 


TDH386.SYS error messages 


There are only two possible error messages associated with 
the TDH386.SYS driver: 


Wrong CPU type: TDH386 driver not installed 


Invalid command line: TDH386 driver not installed 
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Protected-mode debugging with 


80386 users! 


[D286 


The TD286 protected-mode debugger takes advantage of the 
capabilities of the 80286 processor to free more memory for the 
program you are debugging. TD286 puts the Turbo Debugger 
program into extended memory above the 1MB address point, 
and leaves a relatively small loader in the lower 640K. This gives 
you more room for the program you are debugging and its 
symbol table. 


Use Turbo Debugger exactly as you normally would. The only 
difference is that your program has more memory to run in. 


If you have an 80386 processor, you can get even more capabilities 
and memory savings by using the TD368 virtual debugger. See 
Chapter 15 for more information. 


Equipment required for the protected-mode 


debugger 


To use the TD286 protected-mode debugger, you must have a 
computer based on the 80286 or 80386 processor. You must also 
have at least 640K of available extended memory. 
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Installing the protected-mode debugger 


Before you use TD286 for the first time, you must run the 
TD286INS configuration program to let TD286 determine some 
hardware characteristics of the system you are running on. To 
configure TD286, run the configuration program by entering 
TD2861NS at the DOS prompt. 


TD286INS asks you to press Spacebar a number of times as it 
determines the characteristics of your hardware. If at any point 
your system hangs and the program does not proceed, just reboot 
and restart the configuration program. The configuration program 
knows where it had a problem and continues with the next phase 
of its testing. 


Once TD286INS runs to completion, TD286 is ready to use. 


starting the protected-mode debugger 


You start the protected-mode debugger with this command-line 
syntax: 


TD286 [options] program [program options] 


TD286 has the same command-line options as regular Turbo 
Debugger, with the exception that it does not allow the ~y option 
that sets the overlay code pool size. This option is not necessary 
because TD286 does not use overlays. 


Differences between Turbo Debugger and 
protected-mode 
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There are a few things you can do in regular Turbo Debugger that 
you can’t do with TD286: 


u When you use the File | DOS Shell command to run a DOS 
command, the program you are debugging is not swapped to 
disk. This means that you may not always have enough 
memory to run other programs from the DOS prompt. 
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m You can’t use TD286 to debug programs that run in protected 
mode, or use a DOS extender that conflicts with that used by 
TD286. 


Running 1D286 on different machines 
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TD286 knows the hardware characteristics of dozens of different 
machines. When you run TD286INS and it reports “Machine 
already in file's database” your machine is already known to 
TD286 and no modification is necessary. 


If TD286INS does execute its tests, it will store your machine's 
hardware characteristics in TD286 and create a file with the .DB 
extension. This file should be sent back to Borland or uploaded 
onto one of our forums on Compuserve so that future versions of 
TD286 will automatically know your computer’s hardware 
characteristics. TD286 can store the characteristics of 10 machines 
other than the ones it starts with. 
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Debugging ISRs and device drivers 


With Turbo Debugger 2.0 you can debug terminate and stay 
resident (TSR) programs and device drivers, as well as conven- 
tional executable files. You can also run Turbo Debugger itself as 
a TSR, while you perform other operations at DOS level or run 
other programs. 


Turbo Debugger 2.0 has three new commands on the file menu 
that are specifically designed to be used for debugging TSRs and 
device drivers. These are the File | Resident, File | Symbol Load, 
and File | Table Relocate commands. 


This chapter gives a brief explanation of what TSRs and device 
drivers are, and provides information on how to debug them with 
Turbo Debugger 2.0. 


What's a TSR? 


TSR stands for “terminate and stay resident.” TSRs are programs 
that stay in RAM after they are finished running. SideKick and 
SuperKey are TSRs; they stay in RAM all the time and are 
invoked using special hot keys. Other TSRs are invoked from 
programs that issue an appropriate software interrupt. Turbo C 
provides a function, geninterrupt, that issues such software 
interrupts. 


TSRs consist of two parts: a transient portion and a resident portion. 
The transient portion is responsible for loading the resident 
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portion into RAM, and for installing an interrupt handler that 
determines how the TSR is invoked. If the TSR is to be invoked 
through a software interrupt, the transient portion places the 
address of the resident portion of the code in the appropriate 
interrupt vector. If the TSR is to be invoked through a hot key, the 
resident portion must modify the DOS interrupt handler for key- 
board presses. 


Wher the transient portion is finished executing, it invokes a DOS 
function that allows a portion of the .EXE file to stay resident in 
RAM after execution is terminated—hence the phrase “terminate 
and stay resident.” The transient portion of the TSR knows the 
size of the resident portion as well as the resident portion’s 
location in memory, and passes this information along to DOS. 
DOS then leaves the specified block of memory alone, but is free 
to overwrite the unprotected portion of memory. Thus the resi- 
dent portion stays in memory, while the transient portion can be 
overwritten. 


The trick to debugging TSRs is that you want to be able to debug 
the resident portion as well as the transient portion. When the 
-EXE file executes, the only code that is executed is the transient 
portion of the TSR. So when you run Turbo Debugger as usual, by 
specifying a file name, the only code you see executed is the 
transient portion, as it installs the resident portion and its inter- 
rupt handlers. In order to debug the resident portion, you must 
set a debugger breakpoint and make Turbo Debugger itself go 
resident. More about this later. 


Debugging the transient portion of a TSR is the same as debug- 
ging any other file. It is only when you start to debug the resident 
portion that anything novel happens. 


Here is how you debug a TSR program: 


1. Compile or assemble the TSR, being sure to incorporate 
symbolic (debugging) information. Use the TASM /ZI or TCC 
-v command-line option, for example, or TPC /V. 

2. If you have to link the TSR, use the /v option to incorporate 
symbolic information. You can use the TDSTRIP -s option to 
move the symbolic information into a separate file, though 
you don’t have to if the program is an .EXE file. 
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3. Now load the TSR program into Turbo Debugger and run the 
transient portion, using the Run | Run command as usual. Go 
ahead and debug the transient portion in the usual way. When 
you finish running the transient portion, the resident portion 
is installed in RAM. The trick now is to debug the resident 
portion. 

4. Set a breakpoint at the beginning of the resident portion of 
your code, using F2. You can instead set breakpoints at some 
other positions in the resident portion, if you want. 


5. Choose the File | Resident command to make Turbo Debugger 
itself go resident. This has nothing to do with making your 
TSR memory-resident; it makes itself go resident when you 
run it in Turbo Debugger, just as it would if you had run it 
from the command line. The only reason you are making 
Turbo Debugger go resident is so you can go back to DOS and 
invoke your TSR, making its resident portion start executing. 


6. When you are back at the DOS command line, execute the 
resident portion of your TSR by pressing its hot key or doing 
whatever else you do to invoke it. Execute your program as 
usual. 


7. When your program hits the breakpoint, Turbo Debugger 
comes back up, with your TSR displayed at the appropriate 
point. Now you can start debugging the resident part of your 
code. (You can also re-enter Turbo Debugger from DOS by 
pressing Cirl-Break twice.) 


A second method of debugging a TSR’s resident portion is to 
execute the TSR from the DOS command line, then use Turbo 
Debugger to debug the area of RAM containing the TSR. 


To use this method, you need the utilities TDMEM, which 
displays a map of how your system’s RAM memory is used, and 
TDDEV, which gives the segment address where your TSR’s 
resident portion is loaded. 


To use this method: 


1. Follow Steps 1 through 2 of the first method to compile or 
assemble your code, and to strip off its symbol table if 
necessary and place it in a .TDS file. If necessary for your 
application, run TDSTRIP with the -¢ option as well, to 
convert your TSR from an .EXE to a .COM file. 
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2. Execute your TSR from the DOS command line by typing its 


name. For example, if your TSR is called TSR.EXE, type TSR at 
the DOS prompt and press Enter. 


. Run TDMEM to see a memory map of your computer. Note 


the segment address at which the resident portion of your TSR 
is loaded. We refer to this segment as Seg. 


. Next, you need to determine the amount of symbol table 


memory you are going to want Turbo Debugger to allocate 
when you call it up. To do this, note the size of your TSR’s 
symbol table (.TDS) file by doing a DIR command from DOS. 


This size is a lower limit on the amount of symbol table 
memory you need to allocate when you load Turbo Debugger, 
since, in addition to the information stored here, Turbo 
Debugger creates a number of tables, temporary and other- 
wise, when it loads the symbol table. A useful rule of thumb is 
that you need to allocate about one and a half times as much 
symbol table memory as the .TDS file occupies on the disk, 
though sometimes you might need more and sometimes you 
can get by with less. Turbo Debugger lets you know if you’ve 
allocated too little symbol table memory by displaying the 
message “Not enough memory to load symbol table” when 
you do a File! Symbol Load (discussed later), so feel free to 
experiment. 


. Load Turbo Debugger without specifying a file name, 


allocating symbol table memory as appropriate with the -sm 
command-line option. The -sm option takes as an argument 
the number of kilobytes of symbol table memory to be 
allocated. For example, if you want to reserve 3K of symbol 
table memory, enter TD -sm3 at the DOS prompt. When you 
load Turbo Debugger, do not specify a file name, since you are 
debugging something that is already in memory. You should 
have the .TDS and source files for your TSR available in your 
default directory, however, so that they can be accessed to 
supply symbolic information. 


. You could now start debugging your TSR by setting break- 


points, making Turbo Debugger go resident, and performing 
some action from the DOS command level that would trigger 
your breakpoint. This opens Turbo Debugger at the 
appropriate place in your code. However, your debugging 
task can be simplified by recalling the symbolic information 
present in your symbol table and source file first. 
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7. Once Turbo Debugger comes up, clear the sign-on message by 
pressing Esc, then load in your TSR’s symbol table with the 
File | Symbol Load command, specifying the appropriate 
symbol table name. If you get a message that there is not 
enough memory to load your symbol table, exit Turbo 
Debugger and start it up again from the DOS prompt using a 
higher value as an argument to -sm. 


8. The symbol table contains a set of symbols tied to relative 
memory locations in your code. The symbols in the symbol 
table are all prefixed by the characters #FILENAME#, where 
FILENAME is the name of your TSR source file. For example, if 
your source file was called TSR.ASM and contained a label 
Intr, the symbol #7SR# INTR marks a location in memory. 

The symbols in the symbol table are offset from each other by 
the correct number of bytes, but the absolute location of the 
first symbol has not been determined because DOS might have 
loaded your TSR at a different absolute memory location than 
the one at which it was assembled. For this reason, you must 
use a command to explicitly locate the first symbol in memory. 


9. Use File! Table Relocate to place the first symbol from the 
symbol table at the proper location in memory. In this way, the 
symbolic information present corresponds with your code. To 
do this, when you are prompted by Turbo Debugger, specify 
the segment address Seg for your TSR that you determined 
from TDMEM. 

The disassembled statements from memory are synchronized 

E> with information from the symbol table. If your source file is 
present, source statements are printed on the same line as the 
information from the symbol table. 


10. Use the Goto command (Citr-G) to go to the segment of RAM 
containing your TSR. Do this either by giving the segment 
address of your TSR, followed by offset 0000H, or by going to 
a specific symbolic label in your code. 


From here on, continue as in the first method, from Step 4 on. 


What's a device driver? 


Device drivers are collections of routines used by DOS to control 
low-level I/O functions. Installable device drivers (as opposed to 
those intrinsic to DOS) are installed by inserting lines such as 
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device = clock.sys 


in your CONFIG.SYS file. When DOS has to perform an I/O 
operation involving a single character, it scans through a linked 
list of device headers looking for a device with the appropriate 
logical name (for example, COM1). In the case of block device 
drivers such as disk drives, DOS keeps track of how many block 
devices have been installed and designates each by a letter, with A 
for the first block device driver installed, B for the second, and so 
on. When you make a reference to drive C, for example, DOS 
knows to call the third block device driver. 


The linked list of device headers contains offsets to the two 
components of the device driver itself, the strategy routine and the 
interrupt routine. 


When DOS determines that a given device driver needs to be 
invoked, it calls the driver twice. The first time the driver is called, 
DOS talks to the strategy routine and passes it a pointer to a 
memory buffer called the request header. The request header 
contains information about what DOS wants the device driver to 
do. The strategy routine simply stores this pointer away for later 
use. On the second call to the device driver, DOS invokes the 
interrupt routine, which does the actual work specified by DOS in 
the request header, such as transferring characters in from a disk. 


The request header specifies what the device driver is to do 
through a byte in the request header called a command code. This 
specifies one of a predefined set of operations all device drivers 
must perform. The set of command codes is different for character 
device drivers than for block device drivers. 


The problem with debugging device drivers is that there is no 
-EXE file to run, since for proper operation, the driver must be 
installed using a DEVICE = DRIVER.EXT command at boot, 
where .EXT = .SYS, .COM or .BIN. This means the device driver 
to be debugged is already resident in memory before debugging, 
as it must be for proper operation. Hence the functions to load 
and relocate symbol tables become very useful, since they can 
restore symbolic information to the disassembled segment of 
memory where the device driver is loaded. The File | Resident 
command is also very useful, as we shall see. 
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Debugging a 


device driver Here is how you debug a device driver using TDREMOTE: 


L 


Compile or assemble the device driver, being sure to 
incorporate symbolic (debugging) information. Use the TASM 
{21 or TCC —v command-line option, for example. 


. Link the device driver using the /v option to incorporate 


symbolic information. 


. Type TDSTRIP -s -c FILENAME, where FILENAME is the name of 


the device you're debugging, to move the symbolic 
information from the .EXE file into a separate .TDS file, and to 
transform the existing .EXE file into a .COM file. 

TDSTRIP -s -c FILENAME 


where FILENAME is the name of the device driver you're 
debugging. Copy the .COM file to the remote system. 


. Modify your CONFIG.SYS file on the remote system by 


adding the line 
device = FILENAME.COM 


. Make sure FILENAME includes the correctpath to find the 


device driver. 


. Reboot your remote system to load the device driver. 
. Run TDDEV to tell you the location in memory on the remote 


system where DOS has loaded your device driver. Note the 
address where your device driver is loaded. We refer to the 
segment portion of this address as Seg. 


. Next you need to determine the amount of symbol table 


memory you will need Turbo Debugger to allocate when you 
call it up. To do this, note the size of your device driver’s 
symbol table (.TDS) file by doing a DIR command from DOS. 


This size is a lower limit on the amount of symbol table 
memory you will need to allocate when you load Turbo 
Debugger, since in addition to the information stored here, 
Turbo Debugger creates a number of temporary and other 
tables when loading the symbol table. A useful rule of thumb 
is that you need to allocate about one and a half times as much 
symbol table memory as the .TDS file occupies on disk, though 
sometimes you need more, and sometimes you can get by with 
less. Turbo Debugger lets you know if you've allocated too 
little symbol table memory by displaying the message “Not 
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9. 


10. 


11. 


12. 


13. 


enough memory to load symbol table” when you do a File| 
Symbol Load (discussed later), so feel free to experiment. 


Load TDREMOTE on the remote system. 


Load Turbo Debugger (using the -r option and the -rp and -rs 
options as needed) without specifying a file name, allocating 
symbol table memory as appropriate by using the -sm 
command line switch. The —~sm switch takes as an argument 
the number of kilobytes of symbol table memory to be 
allocated. For example, if you wish to reserve 3K of symbol 
table memory, type TD -sm3 at the DOS prompt. When you 
load Turbo Debugger, you do not specify a file name because 
you are debugging something that is already in memory. You 
should have the .TDS and source files for your device driver 
available in your default directory, however, so that they can 
be accessed to supply symbolic information. 


You could now start debugging your device driver by setting 
breakpoints, making Turbo Debugger go resident, and 
performing some action from the DOS command level on the 
remote system which would trigger your breakpoint. This 
would open Turbo Debugger at the appropriate place in your 
code. However, your debugging task can be simplified by 
recalling the symbolic information present in your symbol 
table and source file first. 


Once Turbo Debugger comes up, clear the sign-on message by 
pressing Esc, then load in your device driver’s symbol table 
using the File | Symbol Load command, specifying the 
appropriate symbol table name. If you get a message that there 
is not enough memory to load your symbol table, exit Turbo 
Debugger and start it up again from the DOS prompt using a 
higher value as an argument to —sm. 


The symbol table contains a set of symbols tied to relative 
memory locations in your code. The symbols in the symbol 
table are all prefixed by the characters #FILENAME#, where 
FILENAME is the name of your device driver source file. For 
example, if your source file was called DRIVER.ASM and 
contained a label Intr, the symbol #DRIVER#INTR marks a 
location in memory. 


The symbols in the symbol table are offset from each other by 
the correct number of bytes, but the absolute location of the 
first symbol is not determined, since DOS may load your 
device driver at a different absolute memory location than the 
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one at which it was assembled. For this reason, you must use a 
command to explicitly locate the first symbol in memory. 


14. Use the File | Table Relocate command to place the first symbol 
from the symbol table at the proper location in memory. In 
this way, the symbolic information present will correspond 
with your code. To do this, specify the segment address Seg for 
your device driver which you determined in Step 6. 


The disassembled statements from memory are synchronized 

> with information from the symbol table. If your source file is 
present, source statements will be printed on the same line as 
the information from the symbol table. 


15. Set any breakpoints in your code. 


16. Choose the File | Resident command to make Turbo Debugger 
itself go resident. This has nothing to do with making your 
device driver memory resident; it goes resident at boot on the 
remote system as a result of the device command in 
CONFIG.SYS. The only reason you are making Turbo 
Debugger go resident is so you can go back to DOS and do 
whatever is necessary to invoke your device driver. 


17. When you are back to the DOS command line on the remote 
system, do whatever is necessary to activate your device 
driver. For example, send information to whatever device it 
controls. 


18. When your program hits the breakpoint, Turbo Debugger 
comes back up with your device driver displayed at the 
appropriate point, and you can begin debugging your code. 
(You can also re-enter Turbo Debugger while DOS is running, 
by pressing Ctrl-Break.) | 


Terminating the debugging session 


To terminate a debugging session, get out of Turbo Debugger in 
the usual way, by choosing the File | Quit command or pressing 
Alt-X. If you’re debugging a TSR, it will be unloaded automatically. 
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Summary of commana-line options 


When you start up Turbo Debugger from the DOS command line, 
you can at the same time configure it using certain options. Here’s 
the general format to use: 


td [options] [program name [program args] ] 


Items enclosed in brackets are optional. Following an option with 
a hyphen disables that option if it was already enabled in the 
configuration file. 
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Table A.1 


Turbo Debugger command- 
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line options 


Option 
—cfilename 


—do 
—dp 
-—ds 


—h, -? 


—r 
-rpN 
-rsN 
—sc 


—sddirectory 
—smN 


-Vvn 
—Vp 
-yN 
—yeN 


What it means 
Startup configuration file 


Other display 
Page flipping 
Swap user screen contents 


Display help screen listing all the 
command-line options 


Process ID switching 
Enable keystroke recording 
Assembler startup 

Set heap size (K) 

Enable mouse 


Debug on remote system; COM1, fast 
COM port for remote link 
Link speed: 1=slow, 2=med, 3=fast 


No case-checking 
Source file directory 
Set symbol table memory size (K) 


rev ea graphics save 
43/50 line display not allowed 
EGA palette save 


Set overlay pool size (K) 
Set EMS overlay area size to N 16K pages 
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Technical notes 


This appendix is for advanced users who want to understand 
some of the technical details that underlie the operation of Turbo 
Debugger. Don’t be put off if this chapter appears to have been 
written in Greek; you don’t have to understand the issues pre- 
sented here in order to become a productive and successful Turbo 
Debugger user. 


Some of the information in this chapter will let you understand 
how Turbo Debugger interacts with DOS, the hardware, and your 
program. This can help you understand how your program’s 
behavior might differ while running under Turbo Debugger. 


You will also learn why you can crash the system without too 
much effort, and, even better, how to avoid it. 


Changed load address and free memory 


When Turbo Debugger loads your program, it is placed after the 
debugger in memory. This has two important results: Your pro- 
gram loads at a higher segment address, and it has less free 
memory available. By loading at a different address, some bugs 
that are the result of accessing memory outside your program 
may appear or disappear. By changing the amount of free 
memory, bugs in your memory allocation or use may be hard to 
duplicate. 
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If you’re using a 386-based computer, you can use the TD386 
virtual debugging program to eliminate those problems. See 
Chapter 15 for information on virtual debugging. 


Crashing the system 


Since the debugger can read and write memory at any address in 
your system, you can inadvertently cause a crash by modifying 
certain memory locations outside your program, such as some 
inside DOS, or the interrupt table starting at memory address 
location zero. 


As an example, changing the hardware clock interrupt vector at 
location 0000h:0040h is almost certain to cause a problem. 


Tracing through DOS and process ID switching 


Turbo Debugger keeps track of the process that is running (either 
itself or your program) so that it can open and close files without 
interfering with your program's file handles. This switching is 
done by using a DOS function call. The switch occurs each time 
your program is started from Turbo Debugger, and each time the 
debugger is re-entered from your program. Since DOS is not re- 
entrant, you can get into trouble by setting breakpoints or tracing 
inside DOS. 


You should use the —i- command-line option to disable process ID 
switching if you want to poke around inside DOS. However, your 
program will then share Turbo Debugger’s file handles, which 
may cause either your program or the debugger to run out of 
them. 


Using the 8087/80287 math coprocessor and emulator 
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Turbo Debugger uses neither the math coprocessor nor the 
software emulator, leaving them both free to be used by your pro- 
gram. You shouldn’t experience any difference between using a 
standalone floating-point program and running it under Turbo 
Debugger. 
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Interrupts used by Turbo Debugger 


Turbo Debugger intercepts several interrupt vectors in order to 
debug your program. The following descriptions let you 
determine if there may be interactions between your program and 
Turbo Debugger. 


Interrupt 1/Interrupt 3 

Turbo Debugger uses these interrupts to process breakpoints and 
instruction single-stepping. If these interrupts are modified by 
your program, Turbo Debugger may not be able to regain control 
at the next breakpoint. Normal applications never use these inter- 
rupts because they are reserved for programs such as debuggers 
that must control the execution of other programs. 


Interrupt 2 

Many hardware debuggers use this interrupt to signal that a 
match condition has occurred. If your program takes over this 
interrupt, these boards and their supporting device drivers may 
not work properly. If you must take over this interrupt, chain on 
to the previous owner of it if you do not want to service the 
interrupt. 


Interrupt 9 

This is the keyboard hardware interrupt, which is used for track- 
ing key presses and release codes. Turbo Debugger chains into 
this interrupt when the user program is running, so that it can 
regain control of a program stuck in a loop. Turbo Debugger 
reinstalls this vector each time your program is restarted, thereby 
allowing a program that modifies this interrupt to keep working 
correctly. 


Debugging using INT 3 and INT | 


If you want to debug a program that uses these interrupts, the 
version of the program you are debugging should only load these 
interrupt vectors when it absolutely must, and restore the old 
contents as soon as it is done using them. This technique mini- 
mizes the amount of code that cannot be debugged. While your 
program has these vectors loaded, you cannot use Turbo 
Debugger to step through your code. 
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Display-saving and mode-switching 


Turbo Debugger usually attempts to save and restore your pro- 
gram’s display mode whenever it runs a piece of your program. If 
you only use the standard ROM BIOS calls to change the display 
mode, all will be well. If you directly manipulate the display 
controller registers, Turbo Debugger may disturb those settings. 


Memory consumption 


EMS support 


When you first start Turbo Debugger, DOS loads it into the first 
free memory above DOS and any resident programs. Then, Turbo 
Debugger allocates a working stack and heap above its program 
code. Your program's symbol table comes next in memory, 
followed by the actual program that you want to debug. 


When you exit back to DOS, Turbo Debugger frees the memory 
used by the symbol table and the program being debugged. If 
your program has allocated any memory blocks with the DOS 
memory allocate function (48), Turbo Debugger frees that 
memory as well. 
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If your system has an expanded memory specification (EMS) 
board, Turbo Debugger will use it to store the symbol table for 
your program being debugged. This leaves more main memory 
free for your program. Turbo Debugger saves and restores the 
state of the EMS driver, letting you debug programs that use EMS 
memory. 


If your program must use all of EMS memory, or if you exper- 
ience interaction problems between your program and Turbo De- 
bugger with both using EMS memory, you can disable EMS 
symbol table use by Turbo Debugger. Use the TDINST installation 
utility to do this or specify —ye0 to disable overlay caching in 
EMS. 
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Interrupt vector saving and restoring 
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Turbo Debugger maintains three separate copies of the first 48 
interrupt vectors in low memory (00 through 2F). 


When Turbo Debugger first starts from the DOS command line, a 
copy is made of the vectors. These vectors are restored when you 
return back to DOS by using the File | Quit (or Alt-X) command. 
These vectors are also restored if you use the File | DOS Shell 
command to enter a DOS command while debugging a program. 


The second set of vectors are Turbo Debugger’s vectors. These are 
in effect whenever Turbo Debugger is running and onscreen. 
They are restored every time Turbo Debugger regains control 
after running your program. 


The third set of vectors are for the program you’re debugging. 
These vectors are restored every time you run or step your pro- 
gram, and are saved every time your program stops and Turbo 
Debugger regains control. This lets you debug programs that 
change interrupt vectors, and at the same time allows Turbo De- 
bugger to use its own version of those same interrupts. 
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Inline assembler keywords 


This appendix lists the instruction mnemonics and other special 
symbols that you use when entering instructions with the inline 
assembler. The keywords presented here are the same as those 
used by Turbo Assembler and MASM. 
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Table C.1 AAA 
8086/8011 86/80286 instruction AAD 
mnemonics AAM 


* Available only when running on the 186 and 286 processor 
** Available only when running on the 286 processor 


Table C.2 BSF 

80386 instruction mnemonics BSR 
BT 
BTC 
BTR 
BTS 
CDQ 
CWDE 
IRETD 
LFS 
LGS 
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LSS 
MOVSX 
MOVZX 
POPAD 
POPFD 
PUSHAD 
PUSHFD 
SETA 
SETB 
SETBE 
SETE 


SETG 
SETL 
SETLE 
SETNB 
SETNE 
SETNL 
SETNO 
SETNP 
SETNS 
SETO 
SETP 


REPNZ 
REPZ 
RET 
REFT 
ROL 
ROR 
SAHF 
SAR 
SBB 
SCASB 
SCASW 
SGDT* 
SHL 
SHR 
SLDT** 
SMSW"** 
STC 
STD 
STI 
STOSB 
STOSW 
STR* 
SUB 
TEST 
WAIT 
VERR** 
VERW** 
XCHG 
XLAT 
XOR 


SETS 
SHLD 
SHRD 
CMPSD 
STOSD 
LODSD 
MOVSD 
SCASD 
INSD 
OUTSD 
JECXZ 
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Table C.3 


80486 instruction mnemonics 


Table C.4 
80386 registers 


Table C.5 
CPU registers 


Table C.6 
Special keywords 


BSWAP INVLPG 
CMPXCHG WBPINVD 
INVD XADD 
EAX EDI 
EBX EBP 
ECX ESP 
EDX FS 
ESI GS 
Byte registers AH, AL, BH, BL, CH, CL, DH, DL 
Word registers AX, BX, CX, DX, SI, DI, SP, BP, FLAGS 


Segment registers CS, DS, ES, SS 


Floating registers ST, ST(0), ST(1), ST(2), ST(3), ST(4), ST(5), ST(6), 
ST(7) 


WORD PTR 
BYTE PTR 
DWORD PTR 
QWORD PTR 
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TBYTE PTR 
NEAR 

FAR 
SHORT 
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80387 instruction mnemonics 
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Table 0.1 


8087/80287 numeric 
coprocessor instruction 
mnemonics 


Table 0.2 


FABS 
FADD 
FADDP 
FBLD 
FBSTP 
FCHS 
FCLEX 
FCOM 
FCOMP 
FCOMPP 
FDECSTP 
FDISI 
FDIV 
FDIVP 
FDIVR 
FDIVRP 
FEN! 
FFREE 


FIADD 
FICOM 
FICOMP 
FIDIV 
FIDIVR 
FILD 
FIMUL 
FINCSTP 
FINIT 
FIST 
FISTP 
FISUB 
FISUBR 
FLD 
FLDCW 
FLDENV 
FLDLG2 
FLDLN2 


FLDL2E 
FLDL2T 
FLDPI 
FLDZ 
FLD1 
FMUL 
FMULP 
FNOP 
FNSTS** 
FPATAN 
FPREM 
FPTAN 
FRNDINT 
FRSTOR 
FSAVE 
FSCALE 
FSETPM* 
FSQRT 


* Available only when running on the 287 numeric coprocessor. 
** On the 80287, the fstsw and fnstsw instructions can use the AX register as an 


operand, as well as the normal memory operand. 


FCOS 
FSIN 
FPREM1 
FSINCOS 


FUCOM 
FUCOMP 
FUCOMPP 


FST 
FSTCW 
FSTENV 
FSTP 
FSTSW* 
FSUB 
FSUBP 
FSUBR 
FSUBRP 
FTST 
FWAIT 
FXAM 
FXCH 
FXTRACT 
FYL2X 
FYL2XP1 
F2XM1 
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Customizing Turbo Debugger 


Turbo Debugger is ready to run as soon as you make working 
copies of the files on the distribution disk. However, you can 
change many of the default settings by running the customization 
program called TDINST. You also can change some of the options 
using command-line options when you start Turbo Debugger 
from DOS. If you find yourself frequently specifying the same 
command-line options over and over, you can make those options 
permanent by running the customization program. 


The customization program lets you set the following items: 


a Window, dialog box, and menu colors 


m Display parameters: screen swapping mode, integer display 
format, beginning display (source or assembler code), screen 
lines, tab column width, maximum tiled Watches size, fast 
screen update, 43-/50-line mode, full graphics saving, User 
screen updating, and log list length 

# Your editor startup command and directories to search for 
source files and the Turbo Debugger help and configuration 
files 

= User input and prompting parameters: interrupt key, history 


list length, beep on error, mouse, keystroke recording, and 
control-key shortcuts 
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Running TDINST 


= Source debugging: language options and case sensitivity 


a NMI intercept, DOS process ID switching, expanded memory 
specification (EMS) for symbol table, remote debugging, OS 
shell swap size, and symbol memory size 


= Display mode 


Colors > 
Display... 

Options > 
Mode for display 
Save 

Quit 


> 
> 


To run the customization program, enter TDINST at the DOS 
prompt. As soon as TDINST comes up, it displays its main menu. 
You can either press the highlighted first letter of a menu option 
or use the T and J keys to move to the item you want and then 
press Enter. For instance, press D to change the display settings. 
Use this same technique for choosing from the other menus in the 
installation utility. To return to a previous menu, press Esc. You 
may have to press Es¢ several times to get back to the main menu. 


setting the screen colors 


Customizing 
screen colors 


Windows 
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Choose Colors from the main menu to bring up the Colors menu. 
It offers you two choices: Customize and Default Color Set. 


If you choose Customize, a third menu appears, with options for 
customizing windows, dialog boxes, menus, and screens. 


To customize windows, choose the Windows command. This 
opens a fourth menu, from which you can choose the kind of 
window you want to customize: Text, Data, Low Level (for 
example, the CPU window), and Other (for example, the 
Breakpoints window). Choosing one of these options brings up 
yet another menu listing the window elements, together with a 
pair of sample windows (one active, one inactive) in which you 
can test various color combinations. The screen looks like this: 
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Figure D.] Turbo Debugger Installation C) 1988, 1990 Borland Int) 


Customizing colors for 
windows AR 


[ Selected text 
1 Breakpoint 


Window background other window 
welected text background 
Ereakpoint 


Sandard foreground 
slected text foreground 


When you select an item you want to change, a palette box pops 
up over the menu. Use the arrow keys to move around in the 
palette box. As you move the selection box through the various 
color choices, the window element whose color you are changing 
is updated to show the current selection. When you find the color 
you like, press Enter to accept it. 


> Turbo Debugger maintains three color tables: one for color, one 
for black and white, and one for monochrome. You can only 
change one set of colors at a time, based on your current video 
mode and display hardware. So, if you are running on a color 
display and want to adjust the black-and-white table, first set 
your video mode to black and white by typing MODE BW80 at the 
DOS prompt, and then run TDINST. 


Dialog boxes If you choose Dialogs from the Customize menu, a menu appears 
listing dialog box and menu elements, with a sample dialog box 
for you to experiment with. 
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The screen looks like this: 


Figure D.2 


Customizing colors for dialog —_—| alla caMR AES 


Ptolors 


Text entry em 
a History item Highlight 
Current item Current item 
List item 2 
——_---——- eck box 
Window background Current item 
list and group background Radio Button 
jext entry background 
otton background 
| Button pm Default aM Active 
Windsw border 
Standard text 
Metive item 
tefault item 


‘ist item 
30t letter 
Scgoll bar 


ist it list item 


As with the Windows menu, choosing an item from the current 
menu opens a palette from which you can choose the color for 
that item. 


Menus _ If you choose Menus from the Customize menu, a menu of menu 
options opens, along with a sample menu. Choosing an item from 
Menu background 


Standard item the menu causes the usual palette to appear. 


Active item 
Hot letter 


screen Choosing Screen from the Customize menu opens a menu from 
Pattern for background » | which you can access another menu with screen patterns and 
Pattern background palettes for screen elements, as well as a sample screen back- 


Pattern foreground ground on which to test them. 
Window move background 


Window move foreground . 


Tne default colors 


If you choose Default Color Set from the Colors menu, an active 
text window and an inactive window appear onscreen, sO you can 
see what the default colors for their elements are. 
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setting Turbo Debugger display parameters 


Figure D.3 
The Display Options dialog 
box 


=. 


Display Swapping 


Choose Display from the main menu to bring up the Display 
Options dialog box. 


Db ——_——_———— 1 re) 
Display swapping * Integer format - Beginning display: 
None se 


a hi 
Smart i Assembler 


Alwa So Both 


‘Screen lines ab size. yax tiled watch —. 
i} (es) 25 {+} 43/50 __— aE 5 (a 


".” ».User screen updating 4 list length 
Fast screen updatem™ Other display . 0 : 
Permit 43/50 linesiiM™ (*) Flip pages fons 
Full graphics save Swap | Ok ws | Cancel wl 


These display options include some you can set from the DOS 
command line when you start up Turbo Debugger, as well as 
some you can set only with TDINST. See page 291 for a table of 
Turbo Debugger command-line options and corresponding 
TDINST settings. 


You use the Display Swapping radio buttons to control how 
Turbo Debugger switches between its own display and the output 
of the program you're debugging. You can toggle between the 
following settings: 


None Don’t swap between the two screens. Use this option if 
you're debugging a program that does not output to 
the User screen. 


Smart Swap to the User screen only when display output may 
occur. Turbo Debugger swaps the screens any time that 
you step over a routine, or if you execute any 
instruction or source line that appears to read or write 
video memory. This is the default option. 


Always Swap to the User screen every time the user program 
runs. Use this option if the Smart option is not catching 
all the occurrences of your program writing to screen. 
If you choose this option, the screen flickers every time 
you step through your program, since Turbo 
Debugger’s screen is replaced for a short time with the 
User screen. 
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Integer Format 


Beginning Display 
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Screen Lines 


> 
Tab Size 


Maximum Tiled 
Watch 


The Integer Format radio buttons let you set how integers are 
displayed. You can toggle between the following options: 


Hex Chooses hexadecimal number display. 
Decimal Chooses decimal number display. 
Both Displays both hexadecimal and decimal. 


The Beginning Display radio buttons determines the language in 
which your program is displayed when Turbo Debugger starts. 
They have the following settings: 


Assembler Assembler Startup: None of your program is 
executed, and a CPU window shows the first 
instruction in your program. 


Source Source startup: Your program’s compiler beginning 
code runs, and you start ina Module window, 
where your source code begins. 


Use these radio buttons to toggle whether Turbo Debugger 
should start up with a display screen of 25 lines or a display 
screen of 43 or 50 lines. 


Only the EGA and VGA can display more than 25 lines. 


In this input box, you can set the number of columns between tab 
stops in a text or source file display. You are prompted for the 
number of columns (a number from 1 to 32); the default is 8. 


This input box sets the number of lines that the Watches window 
can expand to when it’s in Tiled mode. You are prompted for the 
number of lines (1 to 20). 
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Fast Screen 


Update The Fast Screen Update check box lets you toggle whether your 
displays will be updated quickly. Toggle this option off if you get 
“snow” on your display with fast updating enabled. You need to 
disable this option only if the “snow” annoys you. (Some people 
prefer the snowy screen because it gets updated more quickly.) 


Permit 43/50 Lines 


Turning this check box on allows big (43-/50-line) display modes. 
If you turn it off, you save approximately 8K, since the large 
screen modes need more window buffer space in Turbo 
Debugger. This may be helpful if you are debugging a very large 
program that needs as much memory as possible to execute in. 
When the option is disabled, you will not be able to switch the 
display into 43-/50-line mode even if your system is capable of 
handling it. 


Full Graphics 


Saving Turning this check box on causes the entire graphics display 
buffer to be saved whenever there is a switch between the Turbo 
Debugger screen and the User screen. If you turn it off, you can 
save approximately 8K of memory. This is helpful if you are 
debugging a very large program that needs as much memory as 
possible to execute. Generally the only drawback to disabling this 
option is a small number of corrupted locations on the User 
screen in graphics mode that don’t usually interfere with 


debugging. 


User Screen 


Updating The User Screen Updating radio buttons set how the User screen 
is updated when Turbo Debugger switches between its screen and 
your programs User screen. There are three settings: 


Flip Pages Puts Turbo Debugger’s screen on a separate 
display page. This option works only if your 
display adapter has multiple display pages, like a 
CGA, EGA, or VGA. You can’t use this option on 
a monochrome display. This option works for the 
majority of debugging situations; it is fast and 
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disturbs only the operation of programs that use 
multiple display pages, such as graphics 
programs. 


Swap Uses a single display adapter and display page, 
and swaps the contents of the User and Turbo De- 
bugger screens in software. This is the slowest 
method of display swapping, but it is the most 
protective and least disruptive. If you are de- 
bugging a program that uses multiple display 
pages, like a graphics program, use this option. 
Also use the Swap option if you shell to DOS and 
run other utilities or if you are using a TSR (such 
as SideKick Plus) and want to keep the current 
Turbo Debugger screen as well. 


Other Display Runs Turbo Debugger on the other display in 
your system. If you have both a color and 
monochrome display adapter, this option lets you 
view your program's screen on one display and 
Turbo Debuggers on the other. 


Log List Length 


Use this input box to set how many previous entries are saved in 
the log file. The maximum number is 200; the minimum is 4. 


Turbo Debugger options 
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nireetonl eee The Options command in the main menu opens a menu of 


Input & prompting... options, which in turn open dialog boxes for you. 
Source debugging... 


Miscellaneous... 


Directories... 
This dialog box contains input boxes in which you can enter: 


Editor program name Specifies the DOS command that starts 
your editor. This lets Turbo Debugger 
start up your favorite editor when you 
are debugging and want to change some- 
thing in a file. Turbo Debugger adds to 
the end of this command the name of the 
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Inout and 
Prompting... 


Figure D.4 
The User Input and Prompting 
dialog box 


History List Length 


Interrupt Key 


Set Key 


Mouse Enabled 


Beep on Error 


file that it wants to edit, separated by a 
space. 


Source directories Sets the list of directories Turbo 
Debugger searches for source files. 


Turbo directory Sets the directory that Turbo Debugger 
will look in for its help and configuration 
files. 


This dialog box lets you set options that control how you input 
information to Turbo Debugger, and how Turbo Debugger 
prompts you for information: 


Lt} Beep on error. | 


| |} Keystroke recording | 
Other | {X} Control ke shortcut: 


This input box lets you specify how many earlier entries are to be 
saved in an history list input box. 


These radio buttons let you assign a default interrupt key. 


If you choose Other, press the Set Key button to choose the actual 
interrupt key. You are prompted for the key to use. 


This check box controls whether Turbo Debugger defaults to 
mouse support. 


By default, Turbo Debugger gives a warning beep when you press 
an invalid key or do something that generates an error message. 
The Beep on Error check box lets you change this default. 
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Keystroke Recording 


Control Key Shortcuts 


Source 
Debugging... 


Figure D.5 
The Source Debugging 
dialog box 


Language 


Ignore Symbol Case 
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This check box determines whether the Execution History 
window defaults to automatic keystroke recording. 


This check box enables or disables the control-key shortcuts. 
When control-key shortcuts are enabled, you can invoke any local 
menu command directly by pressing the Ctrl key in combination 
with the first letter of the menu item. However, in that case, you 
can’t use those control keys as WordStar-style cursor-movement 
commands. 


The Source Debugging dialog box lets you specify what language 
Turbo Debugger will use for evaluating expressions, and enables 
and disables case sensitivity. 


ource debugging 


Language 
e) Source module 
C 


Pascal 
Assembler 


rT J Ignore symbol case im 
| OK 


The Language radio buttons toggle the language Turbo Debugger 
uses for evaluating expressions: 


Source Module Choose what language to use based on the 
languages of the current source module. 


Cc Always use C expressions, no matter what 
language the current module was written in. 


Pascal Always use Pascal expressions, no matter 
language the current module was written in. 


Assembler Always use assembler expressions, no matter 
what language the current module was written 
in. 


If this check box is turned on, Turbo Debugger defaults to treating 
uppercase and lowercase the same. If it is off, case sensitivity is in 
effect. 
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Miscellaneous 
Options... 


Figure D.6 
The Miscellaneous Options 
dialog box 


NMI Intercept 


Use Expanded Memory 


Change Process ID 


Warning! 
DOS Shell Swap Size 


Spare Symbol Memory 
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The Miscellaneous Options dialog box contains options control- 
ling NMI interrupts, EMS memory, use of process IDs DOS shell 
swapping, symbol table size, and remote debugging. 


a] —————-———-jscellaneous option 


NMI intercept 
Use expanded menory 
Change process ID 


Remote debugging 
Remote link port 
¢ ¢ 


20S shell swap size (Kb) 
Link dy eed 


gprs syaol enor (Ko) symbol memory (39) m0 baud 
40 Kbaud 
115 Kbaud 


eee 


If your computer is a Tandy 1000A, IBM PC Convertible, or NEC 
MultiSpeed, or if Turbo Debugger hangs loading your system, 
run TDINST and turn off the NMI Intercept check box. Some 
computers use the NMI (nonmaskable interrupt) in ways that 
conflict with Turbo Debugger, so you must disable Turbo 
Debugger’s use of this interrupt in order to run the program. 


Use this check box to toggle whether Turbo Debugger uses EMS 
memory for symbol tables. You can enable this option even if 
your program uses EMS as well. 


Use this check box to control whether Turbo Debugger uses 
process ID switching. 
Do not turn this check box off unless you are tracing through DOS 


and have a good understanding of the technical issues discussed 
in Appendix B. 


Determines how much of the user program is swapped to disk 
when you shell to DOS; if you enter 0, the whole program is 
swapped. 


This input box lets you specify the amount of memory set aside 
for manually loaded symbol tables. 
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Remote Debugging 


Warning! 


Remote Link Port 


Link Speed 


This check box lets you toggle between enabling and disabling the 
remote link. 


Usually you won’t want to turn this check box on, since that will 
mean that Turbo Debugger will start up every time using the 
remote link. 


The Remote Link Port radio buttons let you choose between using 
the COM1 or COM2 serial port for the remote link. 


The Link Speed radio buttons let you choose one of the three 
speeds that are available for the remote link: 9600 baud, 40,000 
baud, or 115,000 baud. 


setting the mode for display 
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Default 
Color 


Black and white 
Monochrome 


Choosing Mode for Display from the main menu opens a menu 
from which you can select the display mode for your system. 


Default 


Turbo Debugger detects the kind of graphics adapter on your 
system and selects the display mode appropriate for if. 


Color 


If you have an EGA, VGA, CGA, MCGA, or 8514 graphics adapter 
and choose this as your default, the display will be in color. 


Black and White 


If you have an EGA, VGA, CGA, MCGA, or 8514 graphics adapter 
and choose this as your default, the display will be in black and 
white. 


Monochrome 


Choose this if you are using a color monitor with a Hercules or 
monochrome text-only adapter. 
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LCD 


Choose this if you have an LCD monitor. 


Command-line options and installation equivalents 


Table D.1 
Turbo Debugger commana- 
line options 


Some of the options described in the previous section can be over- 
ridden when you start Turbo Debugger from DOS. The following 
table shows the correspondence between Turbo Debugger com- 
mand-line options and the TDINST program command that 
permanently sets that option. 


Option 


-—do 
—dp 
—ds 


—-k 
—-k- 


-p 
—p- 


- 
—r— 


-rp1 
—rp2 


—rs1 
-rs2 
-rs3 


TDINST menu path 


Display 


Options | Miscellaneous 


Options | Input and Prompting 


Display 


Options | Input and Prompting 


Options | Miscellaneous 


Options | Miscellaneous 


Options | Miscellaneous 


Options | Source Debugging 


Options | Directories 
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Dialog box and option 


Display Options 
(°) Other Display 
(*) Flip Pages 
(*) Swap 


Miscellaneous Options 
[X] Change Process ID 
{ ] Change Process ID 


User Input and Prompting 
[X] Keystroke Recording 
[ ] Keystroke Recording 


Display Options 
(*) Assembler 
(*) Source 


User Input and Prompting 
[X] Mouse Enabled 
{ ] Mouse Enabled 


Miscellaneous Options 
[X] Remote Debugging 
[ ] Remote Debugging 


Miscellaneous Options 
(*) COM1 
(*) COM2 


Miscellaneous Options 
(*) 9600 Baud 
(*) 40 KBaud 
(*) 115 KBaud 


Source Debuggin 
[X] Ignore Symbol Case 
{ ] Ignore Symbol Case 


Directories 
Source Directories 


29) 


cy 


Table D.1: Turbo Debugger command-line options (continued) 


Option TDINST menu path Dialog box and option 
Options | Miscellaneous Miscellaneous Options 

-sm Spare Symbol Memory 
Display Display Options 

-vn { ] Permit 43/50 Lines 

—vn- [X] Permit 43/50 Lines 


For a list of all the command-line options available for 
TDINST.EXE, enter the program name followed by -h: 


When you're through... 


Saving changes 


Save configuration file... 
Modify td.exe 


Save Configuration File 
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Modify TD.EXE 


cy 


When you have all your Turbo Debugger options set the way you 
want, choose Save from the main menu to determine how you 
want them saved. 


If you choose Save Configuration File, a dialog box opens, initial- 
ized to the default configuration file TDCONFIG.TD. You can 
accept this name by pressing Enter, or you can type a new 
configuration file name. If you specify a different file name, you 
can load that configuration by using the ~-c command-line option 
when you start Turbo Debugger. For example, | 


td -cmycfg myprog 


You can also use the Turbo Debugger Options | Restore Configu- 
ration command to load a configuration once you have started 
Turbo Debugger. 


If you choose Modify TD.EXE, any changes that you have made to 
the configuration are saved directly into the Turbo Debugger 
executable program file TD.EXE. The next time you enter Turbo 
Debugger, those settings will be your defaults. 


If at any time, you want to return to the default configuration that 
Turbo Debugger is shipped with, copy TD.EXE from your master 
disk onto your working system disk, overwriting the TD.EXE file 

that you modified. 
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Exiting TDINST 


To get out of TDINST at any time, choose Quit from the main 
menu. 
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Remote debugging 


Turbo Debugger’s remote capability is not like that offered by 
other debuggers. With other debuggers, you merely control the 
debugger from the remote system; the debugger and the program 
being debugged are both still on the same system. This can cause 
problems if the program you are debugging requires more 
memory than that left after the debugger is loaded. TDREMOTE, 
supplied as part of the Turbo Debugger package, solves this 
problem by letting you run Turbo Debugger on one system and 
the program you are debugging on another system. 


In this appendix, we'll look at how to debug very large programs 
by using a second PC connected to your main PC. 


Of course, you’re probably wondering, “Why use remote de- 
bugging?” As an example, if the program you want to debug 
won't load under Turbo Debugger, you’re a candidate for remote 
debugging. If you get the message “Not enough memory to load 
symbol table,” or the message “Not enough memory” when you 
attempt to load a program to debug, you may want to consider 
remote debugging. 


Sometimes, your program will load properly under Turbo 
Debugger, but there may not be enough memory left for it to 
operate properly. This is another situation where you may want 
to use remote debugging. 


If you’re experiencing memory problems debugging a program 
and your system has EMS memory, make sure you’re using EMS 
it for symbol tables. Usually, Turbo Debugger does this automati- 
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cally. You can use the configuration utility (TDINST) to control 
whether Turbo Debugger uses EMS for symbol tables. You can 
use TDREMOTE to debug TSRs and device drivers that can’t be 
debugged on a single machine. 


setting up a remote debugging system 


In order to use the remote debugging facility, you’ll need the 
following equipment: 


ma development system with a serial port 


m another PC with a serial port and enough memory and disk 
space to hold the program you want to debug 


wa “null modem” or “printer” cable to connect the two systems 


Make sure that the cable you use to connect the two systems is set 
up properly. You can’t use a “straight through” extension-type 
cable. The cable must, at the very least, swap the transmit and 
receive data lines. (A good computer store should be able to sell 
you what you need.) 


Once you have procured a suitable cable, use it to connect the two 
serial ports. This completes the hardware setup required for the 
remote link. 


Remote software installation 
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Copy the remote debugging driver TDREMOTE.EXE onto the 
remote system. You must also put on the remote system any files 
required by the program you are debugging. This includes data 
input files, configuration files, help files, and so on. 


You can put files on the remote system by using floppy disks, or 
you can use the TDRF remote file transfer utility described in the 
disk-based documentation for the Turbo Debugger utilities. 


You can, if you want, put a copy of the program you want to 
debug onto the remote system. This is not essential, since Turbo 
Debugger will send it over the remote link if necessary. 
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Starting the 


remote link When you start the TDREMOTE driver program on the remote 
system, make sure that your current directory is set where you 
want it. This is important because TDREMOTE puts the program 
you are going to debug into the current directory at the time 
TDREMOTE was started. 


Before starting TDREMOTE, determine whether your serial port 
on the remote system is set up as COM1 or COM2. If your serial 
port is set up as COMI, start up TDREMOTE by typing 


TDREMOTE -rpl -rs3 


If your serial port is set up as COM2, start up TDREMOTE by 
typing 
TDREMOTE -rp2 -rs3 


Both of these commands start the remote link at its maximum 
speed (115 Kbaud). This will work with most PCs and cable 
setups. Later, we'll tell you how to start the link at a slower speed 
if you experience communication difficulties. 


TDREMOTE will sign on with a copyright message and indicate 
that it is waiting for you to start Turbo Debugger on the other end 
of the link. If you want to stop and return to DOS, just press Ctrl- 
Break. 


starting Turbo 


Debugger on the To start Turbo Debugger using the remote link, add the following 
remote link Ptions to the command line you use to start Turbo Debugger 
from DOS: 


Bp For serial port COMI: -rpi -rs3 

o For serial port COM2: -rp2 -rs3 

When the link is successfully started, the message “Turbo 
Debugger online” appears on the remote system, and the message 
“TDREMOTE online” appears on the Turbo Debugger screen. 


This will be quickly replaced with Turbo Debugger’s normal 
window display. 


Notice that both Turbo Debugger and TDREMOTE use the same 
command-line options to set the speed and serial port. Both Turbo 
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Debugger and TDREMOTE must be set to the same speed (-rs 
option) to work properly. 


Turbo Debugger also has the -r command-line option, which 
indicates to start the remote link using the default speed and 
serial port. Unless you’ve changed the defaults using TDINST, -r 
specifies COM1 at 115,000 baud (the fastest baud speed.) 


Here’s a typical Turbo Debugger command line to start the remote 


td -rs3 myprog 


This begins the link on the default serial port (usually COM1) at 
the highest link speed (115 Kbaud), and loads the program myprog 
into the remote system if it’s not already there. 


About loading the pro- Turbo Debugger is smart about loading the program onto the 
gram to the remote remote system. It looks at the date and time of the copy of the 
system program on the local system and the remote system. If the local 

copy is later than the remote copy, it presumes you've recompiled 
or linked the program and sends it over the link at the highest 
link speed; this happens at a rate of about 11K /second. This 
means a typical 60K program will take about 6 seconds to transfer, 
so don’t be alarmed if there’s a delay when you want to load a 
new program. 


To indicate that something’s happening, the screen on the remote 
system counts up the bytes of the file as they are transferred. 


TDREMOTE 


command-line Here is a complete list of all the command-line options supported 
options by TDREMOTE. You can start an option with either a hyphen (-) 


or a slash (/). 
-?or-h Displays a help screen 
—rp1 Port 1 (COM1); default 
—rp2 Port 2 (COM2) 
—rs1 Slow speed, 9600 baud 
—rs2 Medium speed, 40,000 baud 
-rs3 High speed, 115,000 baud (default) 
-—wW Writes options to executable program file 


If you start TDREMOTE with no command-line options, it uses 
the default port and speed built into the executable program file 
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(COM1 and 115,000 baud), unless you have changed them with 
the -w option. 


You can make the TDREMOTE command-line options permanent 
by writing them back into the TDREMOTE executable program 
file on disk. Do this by specifying the -w command-line option 
along with the other options that you want to make permanent. 
You are then prompted for the name of the executable program. 
You can enter a new executable file name that does not already 
exist. TDREMOTE will create the new executable file. 


Note: For a list of all the command-line options available for 
TDREMOTE, enter the program name followed by -h: 


TDREMOTE -h 


If you are running on DOS 3.0 or later, the prompt indicates the 
path and file name that you executed TDREMOTE from. You can 
accept this name by pressing Enter, or you can enter a new 
executable file name. The new name must already exist and be a 
copy of the TDREMOTE program that you have already made. 


If you are running on a DOS 2.0, you'll have to supply the full 
path and file name of the executable program. 


Remote debugging sessions 


Once you've started TDREMOTE and Turbo Debugger in remote 
mode, you can debug your program much as if you were doing it 
on a single system. Turbo Debugger commands work exactly as 
usual; there is nothing new to learn. 


Remember that since the program you are debugging is actually 
running on the remote system, any screen output or keyboard 
input to the program happens on the remote system. The 
Window | User Screen command has no effect when you are 
running on the remote link. 


The CPU type of the remote system appears as part of the CPU 
window title, with the word “REMOTE” before it. 


If you want to send files over to the remote system while you are 
running Turbo Debugger, you can go to DOS using the File | DOS 
Shell command and then use the TDRF utility to perform file 
maintenance activities on the remote system. You can then return 
to Turbo Debugger by typing EXIT at the DOS prompt and 
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TDREMOTE 
messages 


continue debugging your program. TDRF is described in the 
disk-based documentation for Turbo Debugger utilities. 


Here is a list of the messages you might receive when you're 
working with TDREMOTE. 


nn bytes downloaded 

A file is being sent to the remote system. This message shows the 
progress of the file transfer. At the highest link speed (115,000 
baud), transfer speed is about 10K per second. 


Can't create file 

TDREMOTE can’t create a file that needs to be sent to it. This can 
happen either if the disk is full, or the file name already exists as a 
directory. 


Can’t modify exe file 

The file name you specified to modify is not a valid copy of the 
TDREMOTE utility. You can only modify a copy of the 
TDREMOTE utility with the —-w option. 


Can't open exe file to modify 
The file name you specified to be modified can’t be opened. You 
have probably entered an invalid or nonexistent file name. 


Download complete 
A file has been successfully sent to TDREMOTE. 


Download failed, write error on disk 

TDREMOTE can’t write part of a received file to disk. This usually 
happens when the disk fills up. You will have to delete some files 
before the file can be successfully downloaded. 


Enter program file name to modify 

If you are running on DOS 3.0 or later, the prompt will indicate 
the path and file name that you executed TDREMOTE from. You 
can accept this name by pressing Enter, or you can enter a new 
executable file name. The new name must already exist and be a 
copy of the TDREMOTE program that you have already made. 


If you're running DOS 2.0, you will have to supply the full path 
and file name of the executable program. 


Interrupted 
You have pressed Ctrl-Break while waiting for communications to 
be established with the other system. 
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Invalid command-line option 
You have given an invalid command-line option when starting 
TDRF from the DOS command line. 


Link broken 
The program communicating with TDREMOTE has stopped and 
returned to DOS. 


Link established 
A program on the other system has just started to communicate 
with TDREMOTE. 


Loading program “name” from disk 
Turbo Debugger has told TDREMOTE to load a program from 
disk into memory in preparation for debugging it. 


Program load failed, EXEC failure 

DOS could not load the program into memory. This can happen if 
the program has become corrupted or truncated. You should 
delete the program file from disk to force Turbo Debugger to send 
a new copy over the link. If this message happens again after 
deleting the file, you should relink it on the other system and try 
again. 

Program load failed; not enough memory 

The remote system does not have enough free memory to load the 
program that you want to debug. This won’t happen except with 
very large programs, since TDREMOTE takes only about 15K of 
memory. 


Program load failed; program not found 

TDREMOTE could not find the program on its disk. This should 
never happen because Turbo Debugger downloads the program 
to the remote system if it can’t find it. 


Program load successful 
TDREMOTE has finished loading the program Turbo Debugger 
wants to debug. 


Reading file “name” from Turbo Debugger 
A file is being sent to Turbo Debugger. 


Unknown request: message 

TDREMOTE has received an invalid request from the other 
system. This message should never occur if the link is working 
properly. If you get this message, check that the link cable is in 
good working order, and if you still keep getting this error, try 
reducing the link speed by using the -rs command-line option. 
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Waiting for handshake (press Ctrl-Break to quit) 

TDREMOTE has been started and is waiting for a program on the 
other system to start talking to it. If you want to return to DOS 
before the other system initiates communication, press the 
Ctrl-Break key combination. 


Getting if all to work 


Since the remote debugging setup involves two different 
computers and a cable going between them, there’s a chance 
you'll run into some difficulty getting everything to work 
together. 


If you do experience any problems, first check your cable hook- 
ups. Next, try running the link at the slowest speed by using the 
-rs1 command-line option when starting up both TDREMOTE 
and Turbo Debugger. If it works okay using -rs1, try -rs2 (the 
middle speed). Some hardware and cable combinations don’t 
always work properly at the highest speed, so if you can only get 
it to work at a lower speed, you might want to try a different 
cable or different computers. 


” 
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Dialog boxes and error messages 


Turbo Debugger displays error messages and dialog boxes at the 
current cursor location. This chapter describes the dialog boxes 
and error and information messages Turbo Debugger generates. 


We tell you how to respond to both dialog boxes and error 
messages. All the dialog boxes and error messages (including the 
startup fatal error messages) are listed in alphabetical order, with 
a description provided for each one. 


Dialog boxes 


Turbo Debugger displays a dialog box when you must supply 
additional information to complete a command. The title of the 
dialog box describes the information that’s needed. The contents 
may show a history list (previous responses) that you have given. 


You can respond to a dialog box in one of two ways: 


m Enter a response and accept it by pressing Enter. 


m Press Esc to cancel the dialog box and return to the menu 
command that preceded the dialog box. 


Some dialog boxes only present a choice between two items (like 
Yes/No). You can use Tab to select the choice you want and then 
press Enter, or press Y or N directly. Cancel the command by press- 
ing Esc. 


Appendix F, Dialog boxes and error messages 303 


304 


For a more complete discussion of the keystroke commands to use 
when a dialog box is active, refer to Chapter 2. 


Here's an alphabetical list of all the messages generated by dialog 
boxes: 


Already recording, do you want to abort? 

You are already recording a keystroke macro. You can’t start 
recording another keystroke macro until you finish the current 
one. Press Y to stop recording the macro; N to continue recording 
the macro. 


Device error — Retry? 

An error has occurred while writing to a character device, such as 
the printer. This could be caused by the printer being unplugged, 
offline, or out of paper. Correct the condition and then press Y to 
retry or N to cancel the operation. 


Disk errorondrive _ - Retry? 

A hard error has occurred while accessing the indicated drive. 
This may mean you don’t have a floppy disk in the drive or, in the 
case of a hard disk, it may indicate an unreadable or unwritable 
portion of the disk. You can press Y to see if a retry will help; 
otherwise, press N to cancel the operation. 


Edit watch expression 
Modify or replace the watch expression. The dialog box is 
initialized to the currently highlighted watch expression. 


Enter address, count, byte value 

Enter the address of the block of memory you want to set toa 
particular byte value, then the number of bytes you want to set, 
followed by the value to fill the block with. 


Enter address to position to 

Enter the address you want to view in your program. You can 
enter a function name, a line number, an absolute address, or a 
memory pointer expression. See Chapter 9 for more on entering 
addresses. 


Enter animate delay (10ths of sec) 

Specify how fast you want the Animate command to proceed. The 
higher the number, the longer between successive steps during 
animation. 


Enter code address to execute to 
Enter the address in your program where you want execution to 
stop. See Chapter 9 for more information on entering addresses. 
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Enter command-line arguments 
Enter the command-line parameters for the program you're 
debugging. 


Enter comment to add to end of log 

Enter an arbitrary line of text to add to the messages displayed by 
the Log window. You can enter any text you want; it will be 
placed in the log exactly as you type it. 


Enter expression for conditional breakpoint 

Enter an expression that must be true (nonzero) in order for the 
breakpoint to be triggered. This expression will be evaluated each 
time the breakpoint is encountered as your program executes. Be 
careful about any side effects it may have. 


Enter expression to evaluate 

Enter an expression whose value you want to know. The value 
and type of the result will be displayed in an error-type window, 
which disappears once the next keystroke is pressed. 


Enter expression to watch 

Enter a variable name or expression whose value you want to 
watch in the Watches window. If you want, you can enter an 
expression that does not refer to a memory location, such as x * y 
+ 4). If the dialog box is initialized from a text pane, you can 
accept the entry by pressing Enter, or change it and enter some- 
thing else entirely. 


Enter inspect start index, range 

Enter the index of the first item in the array you want to view, 
followed by the number of items you want to view. Separate the 
two scalars by a space or a comma (,). 


Enter instruction to assemble 

Enter an assembler instruction to replace the one at the current 
address in the Code pane. Appendix C has a condensed listing of 
all assembler keywords, and Chapter 11 discusses the assembler 
language in more detail. 


Enter log file name 

Enter the name of the file you want to write the log to. Until you 
issue a Close Log File command, all lines sent to the log will be 
written to the file, as well as displayed in the window. The default 
file name has the extension .LOG and is the same file name as the 
program you are debugging. You can accept this name by press- 
ing Enter, or type a new name instead. 
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Enter memory address 
Enter a single memory address. You can use a symbol name ora 
complete expression. 


Enter memory address, count 

Enter a memory address, followed by an optional comma and the 
number of items. You can use a symbol name or a complete 
expression. 


Enter name of configuration file 

Enter the name of a configuration file to read or write. If you are 
reading froma configuration file, you can enter a wildcard mask 
and get a list of matching files. 


Enter name of file to view 
You can use DOS-style wildcards to get a list of file choices, or 
you can type a specific file name to load. 


Enter new bytes 
Enter a byte list that will replace the bytes at the position in the 
file marked by the cursor. See Chapter 9 for a complete descrip- 
tion of byte lists. 


Enter new coprocessor register value 

Enter a new value for the currently highlighted numeric 
coprocessor register. You can enter a full expression to generate 
the new value. The expression will be converted to the correct 
floating-point format before being loaded into the register. 


Enter new data bytes 

Enter a byte list to replace the bytes at the position in the segment 
marked by the cursor. See Chapter 9 for a complete description of 
byte lists. 


Enter new directory 
Enter the new drive or directory name that you want to become 
the current drive and directory. 


Enter new file offset 

You are viewing a disk file as hexadecimal data bytes. Enter the 
offset from the start of the file where you want to view the data 
bytes. The file will be positioned at the line that contains the offset 
you specified. 


Enter new line number 

Enter the line number you want to see in the current module. If 
you enter a line number that is past the end of the file, you’ll see 
the last line in the file. Line numbers start at 1 for the first line in 
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the file. The current line number that the cursor is on is shown as 
the first line of the Module window. 


Enter new relocation segment value 

Enter an expression in the current language. This value will be 
used to set the base segment address of a symbol table that you 
loaded with the File | Symbol Load command. The expression that 
you enter should evaluate to the segment number of the start of 
the code for which the symbol table applies. 


Enter new value 
Enter a new value for the currently highlighted CPU register. You 
can enter a full expression to form the new value. 


Enter port number 
Enter the I/O port number you want to read from; valid port 
numbers are from 0 to 65,535. 


Enter port number, value to output 

Enter the I/O port number you want to write to, and the value to 
write; separate the two expressions with a comma. Valid port 
numbers are from 0 to 65,535. 


Enter program name to load 

Enter the name of a program to debug. You can use DOS-style 
wildcards to get a list of file choices, or you can type a specific file 
name to load. If you do not supply an extension to the file name, 
-EXE will be appended. 


Enter read file name 

Enter a file name or a wildcard specification for the file you want 
to read into memory. If you supply a wildcard specification or 
accept the default *.*, a list of matching files will be displayed for 
you to select from. 


Enter search bytes 

Enter a byte list to search for starting at the position in memory 
marked by the cursor. See Chapter 9 for a complete description of 
byte lists. 


Enter search instruction or bytes 

Enter an instruction, as you would for the Assemble local menu 
command, or enter a byte list as you would for a Search com- 
mand in a Data pane. 


Enter search string 
Enter a character string to search for. You can use a simple wild- 
card matching facility to specify an inexact search string; for 
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example, use * to match zero or more of any characters, and ? to 
match any single character. 


Enter source address, destination, count 

Enter the address of the block you want to move, the number of 
bytes to move, and the address you want to move them to. 
Separate the three expressions with commas. 


Enter source directory path 

Enter a list of directories, separated by spaces or semicolons (;). 
These directories will be searched, in the order that they appear in 
this list, for your source files. 


Enter symbol table name . . 

Enter the name of a symbol table to load from disk. Usually these 
files have an extension of .TDS. You must explicitly supply the 
file-name extension. 


Enter tab column spacing 

Enter a number between 1 and 32 that specifies how far apart tab 
columns will be when Turbo Debugger displays files in a File or 
Module window. 


Enter variable to inspect 

Enter the name of a variable or expression whose contents you 
want to examine. If the dialog box is initialized from a text pane, 
you can accept the entry by pressing Enter or change it and enter 
something else. 


Enter write file name 
Enter the name of the file you want to write the block of memory 
to. 


Overwrite__ ? 

You have specified a file name to write to that already exists. You 
can choose to overwrite the file, replacing its previous contents, or 
you can cancel the command and leave the previous file intact. 


Overwrite existing macro on selected key? 

You have pressed a key to record a macro, and that key already 
has a macro assigned to it. If you want to overwrite the existing 
macro, press Y; otherwise, press N to cancel the command. 


Pick a method name 
You have specified a routine name that can refer to more than one 
method in an object. Pick the correct one from the list presented. 
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Pick a module 

Select a module name to view in the Module window. You are 
presented with a list of all the modules in your program. If you 
want to view a file that is not a program module, use the View | 
File menu command. 


Pick a source file 
Select a source file from the list displayed; only the source files 
that make up the current module are shown. 


Pick a symbol 

Pick a symbol from the list of displayed symbols. You can start to 
type a name, and you will be positioned to the first symbol, start- 
ing with what you have typed so far. 


Pick a window 
Pick a window from the list of active window titles. 


Press key to assign macro to 

Press the key that you want to assign the macro to. Then, press 
the keys to do the command sequence that you want to assign to 
the macro key. The command sequence will actually be per- 
formed as you type it. To end the macro recording sequence, 
press the key you assigned the macro to. This macro will be 
recorded on disk along with any other keystroke macros. 


Press key to delete macro from 
Press the key for the macro that you want to delete. The key will 
then be returned to its original pre-macro function. 


Program already terminated, reload? 

You have attempted to run or step your program after it has 
already terminated. If you choose Y, your program will be 
reloaded. If you choose N, your program will not be reloaded, and 
your run or step command will not be executed. 


Program out of date on remote; send over link? 

You are running Turbo Debugger over the remote link, and the 
program you want to debug is either not on the remote system or 
it is older than the version on the main system. If you respond Y, 
the new program will be sent over the remote link. If you respond 
N, the load command will be aborted. If you are running at the 
slowest remote speed, you may want to copy the program to the 
remote system manually by using a floppy disk. At the highest 
link speed, the data transfer rate is at least as fast as using a 
floppy disk. 
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Error messages 


Reload program so arguments take effect? 

You have just changed the command-line arguments for the pro- 
gram you're debugging. If you type Y, your program will be 
reloaded and set back to the start. You usually want to do this 
after changing the arguments because programs written in many 
Borland languages only look at their arguments once—just as the 
program is loaded. Any subsequent changes to the program 
arguments won’t be noticed until the program is restarted. 
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Fatal errors 


Turbo Debugger uses error messages to tell you about things you 
haven’t quite expected. Sometimes the command you have issued 
cannot be processed. At other times the message warns that 
things didn’t go exactly as you wanted. 


Error messages are normally accompanied by a beep. You can 
turn off the beep in the customization program, TDINST. 


All fatal errors cause Turbo Debugger to quit and return to DOS. 
Some fatal errors are the result of trying to start Turbo Debugger 
from DOS. A few others occur if something unrecoverable 
happens while you are using the debugger. In either case, after 
having solved the problem, your only remedy is to restart Turbo 
Debugger from the DOS prompt. 


Bad configuration file 
The configuration file is either corrupted or not a Turbo Debugger 
configuration file. 


Could not create dummy PSP segment 

When starting the TD386 virtual debugger with no program to 
load, the dummy program could not be created. Try starting 
TD386 with a program to debug. 


Fatal EMS Error 

The EMS memory driver returned an unrecoverable error indi- 
cation. Either your EMS hardware is malfunctioning, or the 
software driver has become corrupted. Reboot your system and 
try again. If the problem persists, it’s probably a problem with 
your EMS hardware. 
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Invalid switch: __ 

You supplied an invalid option switch on the DOS command line. 
Appendix A has an abbreviated list of all command-line switches, 
and Chapter 4 discusses each one in detail. 


Not enough memory 
Turbo Debugger ran out of working memory while loading. 


Old configuration file 

You have attempted to start Turbo Debugger with a configuration 
file for a previous version. You must create new configuration 
files for this version of Turbo Debugger. 


Remote link timeout 

The connection to the remote system has been disrupted. Try 
rebooting both systems and starting again. If the problem persists, 
refer to Appendix E, where debugging on a remote system is 
discussed. 


Unsupported video adapter 

Turbo Debugger can’t determine what display adapter you are 
using; MDA, CGA, EGA, VGA, MCGA, Hercules, Compaq 
composite, AT&T, and close compatibles are supported. 


Wrong version of TDREMOTE 

You have an incompatible version of TDREMOTE running on the 
remote system. You must use the same release of Turbo Debugger 
and TDREMOTE together. 


Other error 


MESSAGES _‘)’ expected 
While evaluating an expression, a right parenthesis was found to 


be missing. This happens if a correctly formed expression starts 
with a left parenthesis and does not end with a matching right 
one. For example, 


3* (744 
should have been 
3* (7 + 4) 


‘:’ expected 

While evaluating a C expression, a question mark (?) separating 
the first two expressions of the ternary ?: operator was encoun- 
tered; however, no matching : (colon) to separate the second and 
third expressions was found. For example, 
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x<0246 
should have been 
x<024: 6 


‘]’ expected 

While evaluating an expression, a left bracket ([) starting an array 
index expression was encountered without a matching right 
bracket (]) to end the index expression. For example, 


table[4 
should have been 
table[4] 


This error can also occur when entering an assembler instruction 
using the built-in assembler. In this case, a left bracket was en- 
countered that introduced a base or index register memory access, 
and there was no corresponding right bracket. For example, 


mov ax,4[si 
should have been 
mov ax,4[si] 


Already logging to a file 

You issued an Open Log File command after having already 
issued the same command without an intervening Close Log File 
command. If you want to log to a different file, first close the 
current log by issuing the Close Log File command. 


Ambiguous symbol] name 

You have entered a symbol name in an expression that does not 
uniquely identify a method in a C++ or object Pascal program, 
and you have chosen not to pick the correct symbol from a list. 
You must pick the proper symbol from the list presented before 
your expression can be evaluated. 


Assignment out of range 

When doing a Pascal assignment, you have attempted to assign a 
value to a variable that is beyond the range of legal values for the 
variable. 


Bad configuration file name 
You have specified a nonexistent file name with the -c 
command-line option. 
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Cannot be changed 

You tried to change a symbol that can’t be changed. The only 
symbols that can be changed directly are scalars (int, long, and so 
forth in C; Byte, Integer, Longint, and Strings in Pascal) and 
pointers and strings in Pascal. If you want to change a structure or 
array, you must change individual elements one at a time. 


Can't execute DOS command processor 

Either there was not enough memory to execute the DOS" 
command processor, or the command processor could not be 
found. Make sure that the COMSPEC environment variable 
correctly specifies where to find the DOS command processor. 


Can’t go resident until user program terminates 

You have attempted to make Turbo Debugger resident before the 
program you are debugging has gone resident itself. Turbo 
Debugger can go resident only when there is no program loaded 
or when the loaded program has run and terminated. 


Can’t have more than one segment override 

You attempted to assemble an instruction where both operands 
have a segment override. Only one operand can have a segment 
override. For example, 


mov es: [bx],ds:ax 
should have been 


mov es: [bx] ,ax 


Can’t set a breakpoint at this address 

You tried to set a breakpoint in ROM, nonexistent memory, or in 
segment 0. The only way to view a program executing in ROM is 
to use the Run | Trace Into command to watch it one instruction at 
a time. 


Can't set any more hardware breakpoints 

You can’t set another hardware breakpoint without first deleting 
one you have already set. Different hardware debuggers support 
different numbers and types of hardware breakpoints. 


Can’t set hardware condition on this breakpoint 

You have attempted to set a hardware condition on a breakpoint 
that is not a global breakpoint. Hardware conditions can only be 
set on global breakpoints. 


Can’t set that sort of hardware breakpoint 
The hardware device driver that you have installed in your 
CONFIG.SYS file can’t do a hardware breakpoint with the 
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combination of cycle type, address match, and data match that 
you have specified. 


Can’t swap user program to disk 

You issued a command that required the program being debug- 
ged to be written to disk, but there is no room on your current 
disk to write it. You will have to make some space on your disk 
before issuing any commands that require the program to be 
swapped. The File | DOS Shell and Edit commands in text panes 
both require the program to be swapped. 


Can’t use same register twice 

You attempted to assemble an instruction that used a base or 
index register twice in the same memory operand. You can only 
use a register once in any operand. For example, 


mov ax, [bx+bx] 
should have been 
mov ax, [bx+si] 


Cannot access an inactive scope 

You entered an expression or pointed to a variable in a Module 
window that is not in an active function. Variables in inactive 
functions do not have a defined value, so you can’t use them in 
expressions or look at their values. 


Constructors and destructors cannot be called 

This error message appears only if you are debugging a program 
that uses objects. You probably tried to evaluate an object method 
that’s either a constructor or a destructor. This is not allowed. 


Destination too far away 

You attempted to assemble a conditional jump instruction where 
the target address is too far from the current address. The target 
for a conditional jump instruction must be within -128 and 127 
bytes of the instruction itself. 


Divide by zero 

You entered an expression using the divide (/, div) or modulus 
operators (mod, %) that had on its right side an expression that 
evaluated to zero. Since the divide and modulus operators do not 
have defined values in this case, an error message is issued. 


Edit program not specified 

You tried to use the Edit local menu command from a Module or 
Disk File window, but you did not specify an editor startup com- 
mand by using the installation program. 
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Error loading program 

DOS was not able to load the program you specified. This could 
mean the file you specified is not a valid .EXE file, or that the .EXE 
file has been corrupted. 


Error opening file __ 
Turbo Debugger couldn’t open the file that you want to look at in 
the File window. 


Error opening log file__ 

The file name you supplied for the Open Log File local menu 
command can’t be opened. Either there is not enough room to 
create the file, or the disk, directory path, or file name you 
specified is invalid. Either make room for the file by deleting 
some files from your disk, or supply a correct disk, path, and file 
name. 


Error reading block into memory 

The block you specified could not be read from the file into 
memory. You probably specified a byte count that exceeded the 
number of bytes in the file. 


Error recording keystroke macros 

An error occurred while writing the recorded macro keystrokes to 
the configuration file. The macro was probably not recorded to 
disk. 


Error saving configuration 
Turbo Debugger could not write your configuration to disk. Make 
sure that there is some free space on your disk. 


Error swapping in user program, press key to reload 

After swapping your program to disk to execute another program 
that you specified, Turbo Debugger is unable to reload your pro- 
gram. This most likely means that you accidentally deleted the 
disk file that your program was swapped to (GWAP.$$$). The 
only thing that the debugger can do is to reload your program 
exactly as if you had issued the File |Open menu command. 


Error writing block to disk 

The block that you specified could not be written to the file that 
you specified. You probably specified a count that exceeded the 
amount of free file space available on the disk. 


Error writing log file 
An error occurred while writing to the log file collecting the 
output from the log window. Your disk is probably full. 
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Error writing to file 

Turbo Debugger could not write your changes back to the file. 
The file may be marked as read-only, or a hard error may have 
occurred while writing to disk. 


Expression accesses more than one scope 

In conjunction with a breakpoint, you entered an expression that 
contains references to variables from too many scopes. In Pascal, 
you can reference local variables and parameters, globals, and 
locals from an outer subprogram (if the breakpoint is in a nested 
procedure or function). In C, you can reference function autos, 
module statics, and program globals, but not autos from more 
than one function. 


Expression too complex 

The expression you supplied is too complicated; you must supply 
an expression that has fewer operators and operands. You can 
have up to 64 operators and operands in an expression. Examples 
of operands are constants and variable names. Examples of 
operators are plus (+), assignment (= or :=), structure member 
selection (->), and set membership (in). 


Expression with side effects not permitted 

You have entered an expression that modifies a memory location 
when it gets evaluated. You can’t enter this type of expression 
whenever Turbo Debugger might need to repeatedly evaluate an 
expression, such as when it is in an Inspector window or Watches 
window. 


Extra input after expression 

You entered an expression that was valid, but there was more text 
after the valid expression. This sometimes indicates that you omit- 
ted an operator in your expression. For example, 


3*44+52 
should have been 

3*4+5/2 
Another example, 

add ax,4 5 
should have been 


add ax, 45 
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You could also have entered a number in the wrong syntax for the 
language you are using, for example, 0xF000 instead of OFO00h 
when you are in assembler mode. 


Help file __—s not found 

You asked for help but the disk file that contains the help screens 
could not be found. Make sure that the help file is in the same 
directory as the debugger program. 


Illegal procedure or function call 
You have attempted to evaluate a function at a time when you 
can’t do so. This can happen in one of three circumstances: 


You are attempting to call a function that is in a Pascal overlay. 

o You are attempting to call a function while your current 
program location is in a Pascal overlay. 

o You are attempting to call an Object Pascal method that has 
been removed by the Turbo Pascal smart linker. 


Immediate operand out of range 

You entered an instruction that had a byte-sized operand com- 
bined with an immediate operand that is too large to fit in a byte. 
For example, 


add BYTE PTR[bx], 300 
should have been 


add WORD PTR[bx] , 300 


Initialization not complete 

You have attempted to access a variable in your program before 
the data segment has been set up properly by the compiler’s 
initialization code. You must let the compiler initialization code 
execute to the start of your source code before you can access 
most program variables. 


Invalid argument list 

The expression you entered contains a procedure or function call 
that does not have a correctly formed argument list. An argument 
list starts with a left parenthesis, has zero or more comma-sepa- 
rated expressions for arguments, and ends with a right paren- 
thesis. Note that Turbo Debugger requires empty parentheses to 
call a parameterless Pascal function or procedure. For example, 


myfunc(1,2 3) 
should have been 
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myfunc (1,2, 3) 
or 


my func () 


Invalid character constant 

The expression you entered contains a badly formed character 
constant. A character constant consists of a single quote character 
(’) followed by a single character, ending with another single 
quote character. For example, 


"Rh = fal 
should have been 

ml = lal 
Invalid far address 
When entering an instruction to assemble, you supplied a badly 
formed far address for the target of a JMP or CALL instruction. A 


far address consists of a pair of hex numbers separated by a colon. 
For example, 


JMP 1234:XYZ 
should have been 


JMP 1234:1000 


Invalid format string 

You have entered a format control string after an expression, but 
it is not a valid format control string. See Chapter 9 for a 
description of format strings. 


Invalid function parameters 
You have attempted to call a function in an expression, but you 
have not supplied the proper parameters to the function call. 


Invalid instruction 

You entered an instruction to assemble that had a valid instruc- 
tion mnemonic, but the operand you supplied is not allowed. This 
usually happens if you attempt to assemble a POP CS instruction. 


Invalid instruction mnemonic 

When entering an instruction to be assembled, you failed to 
supply an instruction mnemonic. An instruction consists of an 
instruction mnemonic followed by optional arguments. For 
example, 


AX, 123 
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should have been 


MOV ax,123 


Invalid operand separator 

You entered an instruction to assemble but didn’t separate the 
operands with a comma. If an instruction has more than one 
operand, you must always use a comma between the operands. 
For example, 


ADD ax 12 
should have been 
ADD ax, 12 


Invalid operand(s) 

The instruction you are trying to assemble has one or more oper- 
ands that are not allowed. For example, a MOV instruction cannot 
have two operands that reference memory, and some instructions 
only work on word-sized operands. For example, 


POP al 
should have been 
POP ax 


Invalid operator/data combination 

You have entered an expression where an operator has been given 
an operand that can’t have the selected operation performed on it. 
For example, you attempt to multiply a constant by the address of 
a function in your program. 


Invalid pass count entered 

You have entered a breakpoint pass count that is not between 1 
and 65,535. You can’t set a pass count of 0. While your code is 
running, a pass count of 1 means that the breakpoint is eligible to 
be triggered the first time it is encountered. 


Invalid register 

You entered an invalid floating-point register as part of an 
instruction being assembled. A floating-point register consists of 
the letters ST, optionally followed by a number between 0 and 7 
within parentheses; for example, ST or ST(4). 


Invalid register combination in address expression 

When entering an instruction to assemble, you supplied an oper- 
and that did not contain one of the permitted combinations of 
base and index registers. An address expression can contain a 
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base register, an index register, or one of each. The base registers 
are BX and BP, and the index registers are SI and DI. Here are the 
valid address register combinations: 


BX BX+SI 
BP BP+SI 
DI BX+DI 
SI BP+DI 


Invalid register in address expression 

You entered an instruction to assemble that tried to use an invalid 
register as part of a memory address expression between brackets 
([]). You can only use the BX, BP, SI, and DI registers in address 
expressions. 


Invalid symbol in operand 

When entering an instruction to assemble, you started an operand 
with a character that can never be used to start an operand, for 
example, the colon (:). 


Invalid typecast 
You entered a expression that contained an incorrectly formed 
typecast. A correct C cast starts with a left parenthesis, contains a 
possibly complex data type declaration (excluding the variable 
name), and ends with a right parenthesis. For example, 

(x *)p 
should have been 


(struct x *)p 


A correct Pascal typecast starts with a known data type, then a left 
parenthesis, then an expression, then ends with a right 
parenthesis. For example, 


Longint (p) 
or 
Word(p*) 


Invalid value entered 
When prompted to enter a memory address, you supplied a float- 
ing-point value instead of an integer value. 


Keyword not a symbol (C and assembler only) 
The C expression you entered contains a keyword where a 
variable name was expected. You can only use keywords as part 
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of typecast operations, with the exception of the sizeof special 
operator. For example, 


floatval = char charval 
should have been 
floatval = (char) charval 


Left side not a record, structure, or union 

You entered an expression that used one of the C structure 
member selectors (. or —>) or the Pascal record field qualifier (.). 
This symbol, however, was not preceded by a record or structure 
name, nor was it preceded by a pointer to a record or structure. 


No coprocessor or emulator installed 

You tried to create a Numeric Processor window using the View | 
Numeric Processor command, but there is no numeric processor 
chip installed on your system, nor does the program you’ re 
debugging use the software emulator. Or the emulator has not 
been initialized. 

No hardware debugging available 

You have tried to set a breakpoint that requires hardware 
debugging support, but you don’t have a hardware debugging 
device driver installed. You can also get this error if your hard- 
ware debugging device driver does not find the hardware it 
needs. 


No help for this context 

You pressed F1 to get help, but Turbo Debugger could not find a 
relevant help screen. Please report this to Borland technical 
support. 


No modules with line number information 

You have used the View | Module command, but Turbo Debugger 
can’t find any modules with enough debug information in them 
to let you look at any source modules. This message usually 
happens when you're debugging a program without a symbol 
table. See the “Program has no symbol table” error message entry 
on page 325 for more information on symbol tables. 


No previous search expression 

You attempted to perform a Next command from the local menu 
of a text pane, but you had not previously issued a Search com- 
mand to specify what to search for. You can only use Next after 
issuing a Search command in a pane. 
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No program loaded 

You attempted to issue a command that requires a program to be 
loaded. There are many commands that can only be issued when 
a program is loaded. For example, none of the commands in the 
Run menu can be performed without having a program loaded. 
Use the File | Open command to load a program before issuing 
these commands. 


No source file for module __ 

No source file can be found for the module you want to view. If 
the source file is not in the current directory, you can use the 
Options | Path for Source command to specify which directory 
your source file(s) are in. 


No type information for this symbol 

You have entered an expression that contains a program variable 
name without debug information attached to it. This can happen 
when the variable is in a module compiled without the correct 
debug information being generated. You can supply type infor- 
mation by preceding the variable name with a typecast expression 
to indicate its data type. 


Not a function name 

You have entered an expression that contains a function call, but 
the name preceding the left parenthesis introducing the function 
call is not a function name. Any time a parenthesis immediately 
follows a name, the expression parser presumes that you intend it 
to be a function call. 


Not a memory referencing expression 

, memory areas and 

You have entered an expression that does not refer to a memory 
location. There are many cases where the expression must refer- 
ence a memory location, not just return a value. For example, the 
Data | Inspect command requires that the data item you inspect be 
a memory area, not just an expression with a result. For example, 


ee Ae he 1) 

does not reference memory, but 
myarray [4] 

does reference a memory location. 


Not an Object Pascal or C++ program 
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Your program is not an object Pascal or C++ program, so it does 
not contain any objects; therefore, command you selected cannot 
be performed. 


Not a record, structure, or union member 

You entered an expression that used one of the C structure 
member selectors (. or —>) or the Pascal record field qualifier (.). 
This symbol, however, was not preceded by a record or structure 
name, nor was it preceded by a pointer to a record or structure. 


Not enough memory for selected operation 

You issued a command that needed to create a window, but there 
is not enough memory left for the new window. You must first 
remove or reduce the size of some of your windows before you 
can reissue the command. 


Not enough memory to load program 

Your program’s symbol table has been successfully loaded into 
memory, but there is not enough memory left to load your pro- 
gram. If your system has EMS memory, make sure that Turbo 
Debugger is set to use it for the symbol table. You can use 
TDINST to set it. 


If you don’t have EMS or your program doesn’t load even with 
EMS, you can hook two systems together and run Turbo 
Debugger on one system and the program you're debugging on 
the other. See Appendix E for more information on how to do this. 
Or consider using TD286 protected-mode or TD386 virtual 
debugging. See Chapters 15 and 16 for more information. 


Not enough memory to load symbol table 

There is not enough room to load your program’s symbol table 
into memory. The symbol table contains the information that 
Turbo Debugger uses when showing you your source code and 
program variables. If you have any resident utilities consuming 
memory, you may want to remove them and then restart Turbo 
Debugger. You can also try making the symbol table smaller by 
having the compiler only generate debug information for those 
modules you are interested in debugging. If you’re using TD386, 
try the -f option to force TD to emulate expanded memory. See 
Chapter15 for details. 


When this message is issued, your program itself has not even 
been loaded. This means you must free enough memory for the 
symbol table and your program. 
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Only one operand size allowed 

You entered an instruction to assemble that had more than one 
size indicator. Once you have set the size of an operand, you can’t 
change it. For example, 


mov WORD PTR BYTE PTR[bx],1 
should have been 


mov BYTE PTR[bx],1 


Operand must be memory location 

You entered an expression that contained a subexpression that 
should have referenced a memory location but did not. Some 
things that must reference memory include the assignment 
operators (=, +=, and so on) and the increment and decrement (++ 
and - -) operators. 


Operand size unknown 

You entered an instruction to assemble, but did not specify the 
size of the operand. Some instructions that can act on bytes or 
words require you to specify which size to use if it cannot be 
deduced from the operands. For example, 


add [bx],1 
should have been 


add BYTE PTR[bx],1 


Overlay not loaded 

You've tried to set a pane in the CPU window to a location in your 
program that is not presently loaded into memory. You can use a 
Module window to examine source code that has not yet been 
loaded into memory, but you can’t look at the underlying instruc- 
tions since they haven’t yet been loaded into memory. 


Path not found 

You entered a drive and directory combination that does not exist. 
Check that you have specified the correct drive and that the direc- 
tory path is spelled correctly. 


Path or file not found 

You specified a non-existent or invalid file name or path when 
prompted for a file name to load. If you do not know the exact 
name of the file you want to load, you can pick the file name from 
a list by pressing Enter when the dialog box first appears. The 
names in the list that end with a backslash (\) are directories, 
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letting you move up and down the directory tree through the 
lists. 


Program has invalid symbol table 
The symbol table attached to the end of your program has become 
corrupted. Re-create an .EXE file and reload it. 


Program has no symbol table 

The program you want to debug has been successfully loaded, 
but it does not contain any debug symbol information. You'll still 
be able to step through the program using a CPU window and 
examining raw data, but you will not be able to refer to any code 
or data by name. 


To create a symbol table in Turbo Pascal (5.0 or later), turn on 
Debug | Standalone Debugging (or use the /v command-line 
option with TPC.EXE). If you’re using Turbo C or Turbo C++, you 
must compile with /v and link your program with TLINK, using 
the /v option, in order to get debug symbol information. If you’re 
using Turbo Assembler, assemble with /zi and link with /v. 


Program linked with wrong linker version 

You are attempting to debug a program with out-of-date debug 
information. Relink your program using the latest version of the 
linker or recompile it with the latest version of Turbo Pascal. 


Program not found 
The program name you specified does not exist. Either supply the 
correct name or pick the program name from the file list. 


Register cannot be used with this operator 

You have entered an instruction to assemble that attempts to use a 
base or index register as a negative displacement. You can only 
use base and index registers as positive offsets. For example, 


INC WORD PTR[12-BX] 
should have been 
INC WORD PTR[12+BX] 


Register or displacement expected 

You have entered an instruction to assemble that has a badly 
formed expression between brackets ([ ]). You can only put 
register names or constant displacement values between the 
brackets that form a base-indexed operand. 
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Repeat count not allowed 

You have entered a format control string that has a repeat count, 
but the expression that you are applying it to can’t havea repeat 
count. 


Run out of space for keystroke macros 
The macro you are recording has run out of space. You can record 
up to 256 keystrokes for all macros. 


Search expression not found 

The text or bytes that you specified could not be found. The 
search starts at the current location in the file, as indicated by the 
cursor, and proceeds forward. If you want to search the entire file, 
press Ctrl-PgUp before issuing the search command. 


Source file _s not found 

Turbo Debugger can’t find the source file for the module you 
want to examine. Before issuing this message, it has looked in 
several places: 


m where the compiler found it 


m in the directories specified by the -sd command-line option and 
the Options | Path for Source command 


@ in the current directory 


w in the directory where Turbo Debugger found the program 
you're debugging 


You should add the directory that contains the source file to the 
directory search list by using the Options | Path for Source 
command. 


Symbol not found 

You entered an expression that contains an invalid variable name. 
You may have mistyped the variable name, or it may be in some 
procedure or function other than the active one, or out of scope in 
a different module. 


Symbol table file not found 
The symbol table file that you have specified does not exist. You 
can specify either a .TDS or .EXE file for the symbol file. 


Syntax error 
You entered an expression in the wrong format. This is a general 
error message when a more specific message is not applicable. 


Too many files match wildcard mask 
You specified a wildcard file mask that included more than 100 
files. Only the first 100 file names will be displayed. 
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Type EXIT to return to Turbo Debugger 

You have issued the File | DOS Shell command. This message 
informs you that when you are done running DOS commands, 
you must type EXIT to return to your debugging session. 


Unexpected end of line 
While evaluating an expression, the end of your expression was 
encountered before a valid expression was recognized. 


For example, 
99 - 22 * 
should have been 
99 - 22 * 4 
And this example, 
SUB AX, 
should have been 


SUB AX, 4 


Unknown character 

You have entered an expression that contains a character that can 
never be used in an expression, such as a reverse single quote ( ‘) 
inC. 


Unknown record or structure name 

You have entered an expression that contains a typecast with an 
unknown record, structure, union, or enum name. (Note that C 
and assembler structures have their own name space different 
from variables.) 


Unknown symbol 

You entered an expression that contained an invalid local variable 
name. Either the module name is invalid, or the local symbol 
name or line number is incorrect. 


Unterminated string 

You entered a string that did not end with a closing quote ("in C, 
‘ in Pascal) If you want to enter a string that contains quote char- 
acters in Pascal, they must contain additional quote characters (’). 
To enter a C string with quote characters, you must precede the 
quote with a backslash (\) character. 


Value must be between 1 and 32 
You have entered an invalid value for the tab width. Tab columns 
must be at least 1 column wide, but no more than 32 columns. 
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Value out of range 
You have entered a value for a Pascal variable that is outside the 
range of allowed values. 


Video mode not available 

You have attempted to switch to 43-/50-line mode, but your 
display adapter does not support this mode; you can only use 
43-/50-line mode on an EGA or VGA. 


Video mode switched while flipping pages 

Your program has changed the video display mode when Turbo 
Debugger is in page flipping mode. This means that the contents 
of your program’s screen may have been lost. You can avoid this 
by using the -ds command-line option to set video swapping 
mode. 


Information messages 


Turbo Debugger generates some information messages that 
appear before the normal windowed display starts up. Here’s a 
description of them. 


TDREMOTE online 

Turbo Debugger has succeeded in establishing communications 
with the TDREMOTE remote debug driver program on the 
remote system. If you specified a program name to load on the 
DOS command line, that file will now be loaded into the remote 
system. 


Waiting for handshake from TDREMOTE (Ctrl-Break to quit) 
You have told Turbo Debugger to debug your program on the 
remote system connected via the serial port (-r, -rs, and -rp 
command-line options). Turbo Debugger is now waiting for the 
remote system to inform it that it is running. 


You can interrupt Turbo Debugger and return to the DOS prompt 
by pressing Ctrl-Break. 
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G 


Using Turbo Debugger with different 
languages 


In this appendix, we have gathered together some tips on how to 
most effectively use Turbo Debugger with different languages. 


Turbo C tips 


Compiler code 


optimizing If you have used the -O command-line option with TCC or the 
Options | Compiler | Optimization command with the Turbo C 
integrated environment to specify optimized code generation, you 
may have difficulty stepping through certain source code areas. In 
particular, if you have multiple or nested if..else statements, it 
may be difficult to stop as each else clause is encountered. A for 
loop is also rearranged i in a manner which makes tracing through 
it a little odd in some situations. , 


To get around these (infrequent) problems, you can either switch 
to assembler-level debugging by opening a CPU window, or you 
can disable optimizing in the compiler while you are debugging. 
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Accessing pointer 


data 


Stepping through 


330 


complex 
expressions 


Many times in C, you use pointers to refer to arrays of data items. 
Normally, Turbo Debugger shows you the single pointed-to item 
when you inspect a pointer variable. To access a pointer as an 
array, you can first inspect the data item with one of the usual 
techniques, such as placing the cursor over the variable in a 
Module window and pressing Ctr-, and then set a range of items 
to look at by using the Range command on the Inspector window 
local menu. For example, if your program contained 


char *p, buf{80]; 
for (p = buf; p < buf + sizeof (buf); ptt) { 


} 


you can examine p as an array of characters by choosing the 
Range command in the Inspector window’s local menu, and 
entering a starting index of 0 and a count of 80. 


If you have a complex expression, such as 


if (isvalid(x) && !useless(x)) { 


} 


you may want to see the result of each subexpression that makes 
up the conditional expression. If there are function calls in the 
expression, press F7 to trace into a function, put the cursor on the 
closing } at the end of the function, and press F4 to run to that 
point. Then, choose the Data | Function Return command to look 
at the value about to be returned. If there are other function calls 
in the conditional expression, you can then press F7 to stop on the 
first line of the next function in the conditional expression. You 
can then repeat this procedure to examine its return value. 


If you have a complex expression that does not contain function 
calls, for example, 


if (x <= 5 && y[z] > 8) { 


} 
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and you want to see the result of evaluating each subexpression, 
you will have to open a CPU window, do assembler-level 
stepping, and watch the subexpression results being put in CPU 
registers. 


Turbo Assembler Tips 


Looking at raw 


hex data You can use the Data! Add Watch and Data | Evaluate/Modify 
commands with a format modifier to look at raw data dumps. For 
example, 


{ES:DI],20m 


specifies that you want to look at a raw hex memory dump of the 
20 bytes pointed to by the ES:DI register pair. 


Source-level 


debugging You can step through your assembler code using a Module win- 
dow just as with any of the high-level languages. If you want to 
see the register values, you can put a Registers window to the 
right of the Module window. 


Sometimes, you may want to use a CPU window and see your 
source code as well. To do this, open a CPU window and choose 
the Code pane’s Mixed command until it reads Both. That way 
you can see both your source code and machine code bytes. 
Remember to zoom the CPU window (by pressing F5) if you want 
to see the machine code bytes. 


Examining and 


changing _ The obvious way to change registers is to highlight a register in 
registers either a CPU window or Registers window. A quick way to 
change a register is to use the Data | Evaluate/Modify command. 
You can enter an assignment expression that directly modifies a 
register’s contents. For example, 


SI = 99 
loads the SI register with 99. 
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Likewise, you can examine registers using the same technique. 
For example, 


Alt-D E AX 


shows you the value of the AX register. 


Turbo Pascal tips 


Stepping through 
initialization Code When you first load your program into Turbo Debugger, the 


Stepping through 
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exit procedures 


Constants 


right-pointing filled arrow points to the begin keyword of the 
main program. The begin actually corresponds to a series of calls 
to the initialization sections of all the units that your program 
uses (assuming they have initialization code). All programs begin 
with a call to the initialization code of the System unit. 


At this point, if you press F7 (the hot key for the Run | Trace Into 
command), you'll trace into the the first unit that has initialization 
code with debug information enabled. If you use F7 to step past 
the end of the first unit’s initialization code, you'll trace into the 
next unit; eventually you'll return to the main program, ready to 
execute the first statement. 


If, on the other hand, you press F8 (the hot key for the Run | Step 
Over command) at the beginning of the program, you will skip 
over all initialization code and begin stepping through the body 
of the main program. 


When your program terminates, control is passed down a chain of 
exit procedures (refer to the chapter titled “Inside Turbo Pascal” 
in the Turbo Pascal Object-Oriented Programming Guide). When you 
step past the end of the main program, Turbo Debugger does not 
trace into the exit procedures. In order to step through this chain, 
place a breakpoint in each exit of the procedures you want to 
debug. 


Constant identifiers are recognized only for scalar and typed 
constants; for example, 
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progran Test; 
const 
= 5; 
B= Pi; 
Message = '/Testing’; 
Caps = ['A’..'2'); 
Digits : string[10] = ’0123456789'; 
begin 
Writeln(A); 
Writeln(B); 
Writeln (Message) ; 
Writeln(‘A’ in Caps); 
Writeln (Digits); 
end, 


In this program, you can inspect A (a scalar constant), Digits (a 
typed constant), B (a floating-point constant), or Message (a string 
constant), but not Caps (a set constant). 


String and set 


temporaries On _ If you’re using the CPU window, be advised that Turbo Pascal 
the stack automatically allocates string and set temporaries on the stack in 
the following way: 


The plus (+) operator, when used with strings, and all string 
functions will reserve stack space for results of these operations. 
This stack space is reserved in the caller's stack frame. Likewise, 
the +, —-, and * set operators will also reserve stack space for inter- 
mediate results. 


Clever 


typecasting The Dos unit defines the internal data format for all the prede- 
fined file types. You can use these declarations to examine the 
data of any file variable. Try entering this program: 


program Typecast; 
uses Dos; 
var 
TextFile : Text; 
IntFile : file of Integer; 
begin 
Assign(TextFile, ‘TEXT.DTA’); 
Rewrite (TextFile) ; 
Assign(IntFile, 'INT.DTA’); 
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Rewrite (IntFile); 

Close (TextFile) ; 

Close(IntFile) ; 
end, 


Now add these four watch expressions: 


IntFile 
TextFile 
FileRec (IntFile),r 
TextRec (TextFile),r 


The first two will display the file status (CLOSED, OPEN, INPUT, 
OUTPUT) and disk file name, while the second two use typecast- 
ing to reveal internal field names and values for the file variables. 


CPU window tips 


for Pascal sm Routines in the System unit are unnamed. When watching a call 
instruction in the CPU window, you will see a call to an abso- 
lute address instead of a symbolic name. 


u A number of I/O routines (for example ReadIn and Writeln) 
often generate multiple assembler-language calls. 


w Range-checking, stack-checking, and I/O-checking generate 
calls to library routines to perform their respective functions. 


a A number of operators (Longint multiplication, string concat- 
enation, and so on) are implemented via calls to library 
routines. 


m The literal constants (string, set, and floating-point) of a 
procedure are placed in the code segment, just before the 
procedure’s entry point. 
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action 


active pane 


active window 


array 
ASCII 


assembler 


autovariable 


block scope 


breakpoint 


button 


Glossary 


The terms listed here are used frequently in this manual. Some of 
them are general terms about software and computers, and others 
are specific to the Turbo Debugger environment. 


What happens when a breakpoint gets triggered. Actions can stop 
your program, log the value of an expression, or execute an 
expression. 


The pane in the active window that is accepting user input. All 
cursor motion and local menu commands act upon this pane. 


The window on the display that the user is interacting with. Only 
one window can be the active window. It has its title in reverse 
video, and a double-line rather than a single-line border. 


A data item composed of one or more items of the same data type. 


The native character set of the IBM PC and many other 
computers. 


A form of machine instructions that humans can read, with 
opcode mnemonics. The Code pane of a CPU window lets you 
assemble instructions directly into memory. 


In the C language, this is a variable in a program that is local to an 
instance of a called function. These variables are stored on the 
stack, and their scope is that of the enclosing block (in C, source 
lines between a pair of {}). 


The region of the program in which a specific data item is 
“visible.” For example, some variables have global scope, meaning 
they are accessible anywhere in your program; other variables 
may be local to a module or procedure. 


An address in the program you are debugging where some action 
is to be performed. See also action. 


A dialog box item, represented by shadowed text, that executes a 
command or confirms settings you have made in the dialog box. 
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casting Converting an expression from one data type to another. For 
example, converting from an integer to a floating-point number. 
In C, a cast consists of a data type enclosed in parentheses, like 
(int). In Pascal, a typecast consists of a type, followed by an 
expression surrounded by parentheses, like word(5). (Also called 
typecasting and type conversion.) 


C expression An expression using the C language syntax. Turbo Debugger lets 
you evaluate any C expression, including those that assign values 
to memory locations. 


check box A dialog box item that toggles a setting between On and Off. 
When the option is set to On, an X appears between the square 
brackets of the check box: [X]. 


CPU The central processing unit; refers to the 80x86 processor in your 
system. The CPU has a number of flags and registers. The CPU 
window shows the current CPU state. 


CPU flag One of the control bits in the CPU that either affects subsequent 
instructions or is set to reflect the results of an operation. 


CPU register A fast storage location inside the CPU chip. The register names 
are AX, BX, CX, DX, SI, DI, BP, SP, CS, DE, ES, SS. 
configuration file A file in either the current directory or in the path that sets Turbo 
Debugger default parameters. 


CS:IP Thecurrent program location, as specified by the code segment 
(CS) CPU register, and the instruction pointer (IP) register. 


default A value automatically supplied when none is specified by the 
user. 


dialog box An onscreen box in which you can view and adjust settings and 
input information. 


disassembler A program that converts machine code into assembler code that 
you can read. The Code pane in a CPU window automatically 
disassembles instructions in one of its panes. 


EMS Expanded memory specification. Turbo Debugger can put your 
programs symbol table in EMS to conserve main memory. 


expression A combination of operators and operands conforming to the 
syntax of one of the languages supported by Turbo Debugger: C, 
Pascal, and assembler. 


global breakpoint A breakpoint that can occur on every instruction or source line. 
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history list 
inspector 
local menu 


menu bar 


operand 
operator 


pane 


PATH 


pop-up menu 


postfix 

prefix 
pull-down menu 
radio buttons 


record 
reverse execution 


Glossary 


A list of previous user input lines maintained for each input box. 
This lets you select a previous entry instead of having to type it in. 


A window used to examine or change the values ina data 
element, array, or structure. 


The menu of commands that apply only to a particular window or 
pane. Press Alt-F10 to pop up the local menu for the current pane. 


The bar at the top of the screen from which pull-down menus come. 
The commands on these menus are always available regardless of 
what you’re doing in Turbo Debugger. Press the Altkey in combi- 
nation with the highlighted letter of a menu bar item to access 
these menus. 


The data item that an operator acts on; for example, in 3 * 4, both 
3 and 4 are operands. 


An action that is performed on one or more operands, such as 
addition (+) or multiplication (*). 


A section of a window that contains logically related information. 
Panes can be scrolled independently of each other. When the size 
of a window is changed, its panes are adjusted to make the best 
use of the new window size. Each pane has a local menu of 
commands. See also active pane. 


The DOS environment variable that indicates where to search for 
executable programs. Turbo Debugger searches the path fora 
configuration file. 


A menu that appears in midscreen, instead of pulling down from 
the menu bar. 


An operator that comes after its operand, like x++ in C. 
An operator that comes before its operand, like - -x in C. 
A menu of commands that pulls down from the menu bar. 


A set of three or more options, one and only one of which must be 
active at any given time. If a radio button is on, a bullet appears 
between parentheses: (¢). 


See structure. 


The process of stepping backward through your program one 
instruction at a time, undoing the effects of program execution as 
you go. 
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scalar 


scope 
set 
stack 


side effect 


step 


structure 


symbol 
trace 
tracepoint 


triggered 


type 


watchpoint 


wildcards 
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A basic data type consisting of ordered components such as Byte, 
Integer, Char, and Boolean in Pascal or char, int, and float in C. 
Scalars can be the individual elements of larger data items, such 
as arrays or structures. 


See block scope. 
An unordered group of elements, all of the same scalar type. 


The region of memory that stores procedure and function return 
addresses, parameters, and other data related to an instance of a 
called procedure or function. 


An expression that alters the value of a variable or memory 
location; for example, an assignment statement or one that calls a 
function in your program that modifies some data. 


To execute the program being debugged one instruction or source 
line at a time, while treating procedure or function calls as a 
single instruction. This lets you skip over calls to routines that 
you don’t want to examine one line at a time. 


A data item composed of one or more elements of possibly 
dissimilar types. 


A name of any variable, constant, procedure, or function. 
To execute a program one instruction or source line at a time. 


A global breakpoint that watches for a variable or memory area to 
change. 


A breakpoint is triggered when all the things controlling it 
become true: Your program must have reached the specified 
address, the pass count must have been reached, and the 
condition must have been satisfied. 


Data items in your program have different types indicating their 
purpose. For example, your program can contain pointers, 
floating-point numbers, arrays, and so on. 


A global breakpoint that watches for an expression to become 
true. 


The characters * and ?, used in file matching expressions. 


? matches any single character 
* matches zero or more characters 


For example, abc*.1 matches abc99.1 and abcdef.1 but not xyz99.1. 
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window A rectangular area of the screen containing information that can 
be viewed independently of the contents of other windows. In 
Turbo Debugger, windows can partially or completely obscure 
one another. See also active window. 
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222? 
in Variables window 77 
in Watches window 107 
8514 graphics adapter 290 
:: (double colon) operator 146, 148 
386“MAX 257 
/$ option (TPC) 62 
32-bit register display 174 
~? option (display help) 
TD386 virtual debugger 250 
—? option (help) 65 
TD386 virtual debugger 249 
TDREMOTE 298 
= (System) menu 194 
activating 18 
80x87 coprocessors 270, See also numeric 
coprocessors 
control bits 187 
CPU data display 178 
instruction mnemonics 278 
registers 277 
status bits 188 
80x86 processors See also 80286 processor; 
80386 processor 
CPU register display 174 
debugging 165-184 
triggering breakpoints 127 
instructions 
assembling 180-182 
mnemonics 276 
operands and 227 
memory allocation 230 
type, in CPU window 167 
80286 processor See also 80x86 processors 
debugging 253-255 
80386 processor See also 80x86 processors 
debugging 247-252 
device driver 11, 248 
exception handlers and 82 


Index 


extended address modes 257 
instructions 229 

mnemonics 276 

TD386 virtual debugger and 257 
registers 145, 251, 276 


A 


About command 5 
accuracy testing 237 
Action Expression input box 179 
Action radio button 179 
active window 37 
returning to 19 
activity indicators 36 
adapters See graphics adapters; video adapters 
Add command 1217, 124 
Add Comment command 123, 124 
Add Watch command 99, 3317 
address, Borland 5 
Address input box 127 
addresses 139, 269 
backtracking through 177 
far 378 
instruction, disassembled 168 
instructions, disassembled 168 
memory See memory, addresses 
returning to previous 770 
running to specified 133, 167, 169, 175 
problems with 84 
scope override for 140 
segment:offset 
physical addresses and 186 
size overrides (built-in assembler) 187 
stack 180 
resetting 780 
switching between 770, 180 
symbol tables, base segment 307 
word pointer chain 176-177 
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addressing modes, 80386 processor 257 
Alt-key shortcuts See hot keys 
Always option 
breakpoints condition 120 
display swapping 77 
ancestor and descendant relationships 156, 157 
ancestor types 162 
Animate command 85, 304 
Another command 30 
arguments 2, See also parameters 
calling function 27 
command-line options 63, 310 
changing 93 
setting 85, 92 
list 317 
Arguments command 93 
arrays 
changing 313 
indexes 305 
inspecting 21, 30, See also Inspector windows 
C tutorial 48 
Pascal tutorial 55 
subranges of 104, 107, 110, 171 
quoted character strings and 153 
watching 100, See also Watches window 
arrow keys See also keys 
history lists and 24 
Inspector windows and 49 
menu commands and 78 
radio buttons and 20 
README file and 8 
resizing windows with 35 
ASCII 
files 205 
editing 136 
searching 135 
text 
viewing files as 134, 135, 136 
text editors and 136 
ASCII display option (files) 136 
.ASM files 260, 264 
Assemble command 171, 180 
assembler See also Turbo Assembler 
built-in 166, 180-182, See also Code pane 
problems with 372 
Turbo Assembler vs. 187-782 
bytes, changing 176 


342 


character strings, searching for 175, 176 
code 29, 185 
skipping over 1717 
tracking 30 
conditional jumps 168, 169, 1817 
data, formatting 174, 177-178 
debugging techniques 165-184 
modules 1777 
inline, keywords 275-278 
problems with 320 
instructions 168, 1717, See also instructions 
back tracing and unexpected side effects 87 
breakpoints and 122 
disassembled 177 
executing single 83 
execution history and 87 
multiple, treated as single 84 
peripheral device control 172 
protected-mode 257 
recording 88 
referencing variables 187 
returning 169, 170 
searching for 170 
problems with 1770 
size overrides and 181-182 
watching 28, See also CPU window 
memory dumps 174, 178, 182 
mode, starting Turbo Debugger in 66 
OFFSET operator 187 
operands 
size overrides 181, 182 
programs 
display modes 777 
returning to 169 
registers 183, See also CPU, registers 
altered 230 
I/O read/writes 172 
incrementing/decrementing 173 
returns, far and near 168, 176, 187 
routines 177 
stack See also Stack window 
examining 7179-180 
symbols 168 


Assembler option (language convention) 138 
assignment operators See also operators 


language-specific 78, 102 
Turbo C 147 
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Breakpoint List pane 118 
Breakpoint Options dialog box 179 
breakpoints 26, 115-127, See also Breakpoints 


expressions with side effects and 98, 148 
Turbo Pascal 157 
At command 117, 124 


Atron debugging board 77 
AUTOEXEC.BAT 6 
virtual debugging and 248 


/B option (black-and-white mode) 17 

Back Trace command 85 

backward trace 15, 87, See also Back Trace 
command; reversing program execution 
addresses, near and far and 177 
assembler instructions 87 
interrupts and 86 

Base Segment:0 to Data command 177 

beep on error, setting 287 

Beep on Error check box (TDINST) 287 


Beginning Display radio buttons (TDINST) 284 


binary operators See also operators 
Turbo C 146 
Turbo Pascal 150 
bits 166 
control, 80x87 coprocessor 187 
CPU register display 174 
status, 80x87 coprocessor 188 
blinking cursor 34 
Block command 178 
blocks 
memory See memory, blocks 
moving 308 
reading from, problems with 315 
writing to files, problems with 315 
Borland 
CompuServe Forum 5 
license agreement 7 
mailing address 5 
technical support 5 
Both option (integer display) 72 


window 
Boolean 121, 125 
complex 121 
conditional 121, 124, 125 
controlling 778 
disabling/enabling 121 
global 82, 125 
memory variables and 120 
testing 125 
hardware-assisted 17, 80 
80386 systems and 127 
device drivers and 126, 313 
memory variables and 120 
problems with 82, 313, 321 
infinite loops and 89 
inspecting 122 
multiple 127 
pass counts See pass counts 
process ID switching and 270 
processing 
interrupts and 277 
reloading programs and 97 
removing 116, 122 
returning information on 80 
running programs to 47, 54 
saving temporarily 127 
scope 118 
setting 116, 118, 121 
conditional 124 
pass counts 7127, 124, 125 
problems with 373 
program termination and 87 
simple 124 
tutorial 47, 53 
skipping 125 
triggering 124 


bottom line See also reference line DORE aa ams and 55 
boundary errors 215 alg ae portion 
Pascal-specific 224 ate 4 5 
testing for 237 with demo programs 
Break option (breakpoints action) 119 viewing 118 
See j Breakpoints command 118 
breaking out of programs 9 


Breakpoints menu 1176, 195 


Bree <polnt Dery paned 18 Breakpoints window 26, 118-122 


Breakpoint Disabled check box 121 
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local menu 118, 197 
opening 178 
panes 178 
bugs 13-15, 211, 213-215 
accuracy testing 237 
assembler-specific 226-231 
Quirks mode 2317 
boundary errors 215 
Pascal-specific 224 
testing for 2317 
C-specific 215-219 
finding 14, 15, 86, 211-212 
backward trace and 85 
demo programs 232-245 
execution history and 86 
history lists and 122 
interrupting program execution and 89 
memory allocation and 247, 269 
in subroutines 274 
fixing 127 
built-in assembler and 187 
incremental testing 273 
off-by-one 173 
Pascal-specific 219-226 
range errors 225 
returning information on 80 
built-in assembler 766, 180-182, See also 
assembler, built-in 
built-in syntax checkers 15 
bullets (¢) 
Result box and 97 
Watches window and 100 
buttons 20, See also dialog boxes 
Help 20 
radio See radio buttons 
Byte command 177 
byte lists 
entering 135, 143 
searching for 170, 175, 176 
text editors and 136 
bytes 166, 168, 176 
command codes and 262 
formatting 174, 177 
hexadecimal 
floating-point registers 186 
viewing files as 134, 136 
memory blocks 179 
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memory blocks set to 304 
raw data 306 

examining 102 

floating-point registers and 186 
reserving in memory 67 
searching for 326 
symbol tables and 261, 264 
watching 28 
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C++ programs 
class instances 
formatting 97 
inspecting 160-163 
class member functions 29, 79 
inspecting 758 
class types 156 
hierarchy tree 29 
inspecting 158-160 
compatibility with Turbo Debugger 155 
debugging 16, 155-163 
nested class structures 158 
this parameter and 97 
expressions, problems with 312 
multiple inheritance 29, 156, 157 
scope override 1417 
stepping through 84 
tracing into 83 
-c option (load configuration file) 64 
problems with 372 
C option (language convention) 138 
C programming language See Turbo C 
calculator 99 
Caller command 170 
case sensitivity 
enabling 289 
overriding 67 
casting See type conversion 
central processing unit See CPU 
CGA 11, See also graphics adapters; video 
adapters 
Change command 
Data pane local menu 176 
Global pane local menu 78 
Inspector window local menu 117 
Object Data Field pane local menu 167 
Register pane local menu 173, 187 
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Stack pane local menu 180 
Static pane local menu 78 
Watches window local menu 107 
Change dialog box 
global symbols and 78 
local symbols and 78 
Change Process ID check box (TDINST) 289 
Changed Memory Global command 117, 125 
Changed Memory option (breakpoints 
condition) 120 
Changed Memory radio button 125, 126 
character constants 378 
character devices, problems with 304 
character strings 
null-terminated 103, 109 
quoted 135 
arrays as 153 
problems with 327 
searching 132, 133, 135, 136 
searching for 175, 176, 307 
Turbo C 145 
Turbo Pascal 150 
characters 
control (Pascal programs) 150 
display (ASCII vs. hex) 136 
escape (Turbo C) 145 
invalid 327 
problems with scalar variables and 103, 106 
raw 153 
value of 103, 106 
check boxes 20, See also dialog boxes 
Beep on Error (TDINST) 287 
Breakpoint Disabled 127 
Change Process ID (TDINST) 289 
Control Key (TDINST) 288 
Fast Screen (TDINST) 285 
Full Graphics Saving (TDINST) 285 
Global 725 
Ignore Symbol Case (TDINST) 289 
Keystroke Recording (TDINST) 288 
Mouse Enabled (TDINST) 287 
NMI Intercept (TDINST) 289 
Permit 43/50 Lines (TDINST) 285 
Remote Debugging (TDINST) 290 
Save Configuration 73 
Use Expanded Memory (TDINST) 289 
class instances See C++ programs 


Index 


class member functions and types See C++ 
programs 
Clear command 178 
close box 32 
Close command 30, 35, 112 
Close Log File command 123 
code See also specific language application 
breakpoints and 122, 124, 125, 126 
checking onscreen 30 
command-line options and source 67 
current segment See programs, current 
location 
debugging See debugging 
disassembled 177 
problems with 77 
editing 129-130 
executing 
TSR programs and 258 
exit, returned to DOS 87 


inspecting 87, 88, See also Inspector windows 


interrupts and, problems with 89 

pool size, setting 68 

skipping over 177 

splice 119 

splicing in 127 

stepping through 84, See also Step Over 
command 
problems with 277 


tracing into 83, See also Trace Into command 


execution history and 86 
viewing 166 
execution history and 29 
in multiple files 132, 136 
watching See also Watches window 
in slow motion 85 
Code pane 168-172 
80x87 coprocessors and 168 
addresses 
symbolic memory 168 
current program location 167 
disassembler and 168 
display modes 177 
immediate operands and 168 
instruction addresses 168 
local menu 169, 198 
codes, release 277 
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color graphics adapters 11, See also graphics 
adapters 
color monitors 65, See also monitors 
customizing 280-282 
color tables 2817 
Colors command (TDINST) 280 
command codes 262 
command-line options 63-69, See also specific 
switch 
arguments 370 
changing 93 
setting 85, 92 
disabling 64 
INSTALL 
/B (black-and-white mode) 717 
-h (help) 70 
overriding 291 
saving 279 
summary of 267-268 
symbol table allocation 
device drivers and 264 
problems with 264 
TSRs and 260 
problems with 267 
symbolic debugging information 
device drivers and 263 
symbolic information 
TSRs and 258 
syntax 63 
help with 65 
TD286 protected-mode debugger 254 
TD386 virtual debugger 249 
~? (help) 250 
-h (help) 250 
TDINST vs. 291-293 
TDREMOTE 298-299 
Turbo Debugger utilities 9 
commands 21, See also specific menu command 
assigning as macros 70 
choosing 78 
active windows and 37 
problems with 322 
dialog boxes and 303 
escaping out of 79 
hot keys and menu 19 
local menu 23 
recording frequently used 97 
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summary of 191-209 
onscreen 36, 38 
comments 
adding to history lists 123 
adding to log 305 
communications, remote systems 290, 301 
debugging over 67, 299, See also 
TDREMOTE 
problems with 302, 311 
Comp command 178 
Compaq EMS simulator 2517 
compiler directives See also specific language 
application 
files and 129 
complex data objects 100 
complex data types 95 
composite monitors 1717 
compound data objects 99 
inspecting 107 
compressed files, unarchiving 10 
CompuServe Forum, Borland 5 
COMSPEC environment variable (DOS) 373 
Condition Expression input box 120, 121 
Condition radio button 120 
conditional breakpoints See breakpoints 
conditions See also breakpoints 
controlling 178 
qualifying 125 
setting 124 
CONFIG.SYS See configuration files 
configuration files 6, 69 
changing default name 73, 293 
device driver debugging and 263 
directory paths 67 
setting 287 
loading 64, 306 
overriding 64, 69 
problems with 310, 311, 312 
saving 293 
macros to 97 
options to 72 
problems with 375 
TDCONFIG.TD 36, 64, 69 
virtual debugging and 248 
constants 
Inspector windows and 102 
problems with 378 
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TASM 152 
Turbo C 145 
Turbo Pascal 150, 332, 334 
constructor methods 98 
problems with 314 
context-sensitive help 36-39 
context-sensitivity 21, 22 
continuous trace 85 
control bits, viewing 787 
control flags 187 
Control Key check box (TDINST) 288 
control-key shortcuts 288, See also hot keys; 
keys 
Control pane 187 
local menu 187, 202 
conversion See type conversion 
coprocessors See 80x87 coprocessors; numeric 
coprocessors 
CPU See also CPU window 
flags 174 
state of 173 
viewing 28, 167, 183 
memory dump 174 
registers 144, 165, 183, 277 
80386 processor 145 
16-bit vs. 32-bit display 174 
compound data types and 99 
decrementing 173 
incrementing 173 
1/O 172 
optimization with 49, 56 
resetting 173 
viewing 28, 173-174, 183 
state, examining 28, 166 
TDREMOTE and 299 
CPU command 102, 166 
CPU window 28, 166-180 
cursor in 167 
disassembled code and 77 
opening 166 
panes 28, 167-180 
problems with 324 
processor type in 767 
program execution and 82-88 
crashes See system, crashes 
Create command 25, 70 
Ctrl-Break (interrupt key) 89 


Index 


device drivers and 265 
problems with 87 
resetting 90, 287 
TSR programs and 259 
current activity, help with 36 
current code segment See programs, current 
location 
cursor 34 
CPU window 167 
running programs to 83 
tutorial 46, 52 
cursor-movement keys See keys 
customer assistance 5 
customizing Turbo Debugger 69, 279-294 
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data 96-99, See also Data pane 
accessing 138 
bashing 
global breakpoints and 126 
formatting 97 
incorrect values 82 
input 232 
inspecting 95-112, See also Inspector 
windows 
in recursive functions 79 
manipulating 28 
modifying 51, 58 
objects 
complex 700 
compound 99, 107 
inspecting 96, 183, See also Inspector 
windows 
pointing at 99 
watching 100, See also Watches window 
raw 
displaying 174 
examining 102, 174-179 
inspecting 183 
viewing 28, 182, 306 
size overrides (built-in assembler) 182 
structures 
inspecting 162 
structures, inspecting 27 
testing, invalid input and 237 
truncated 97 
types 95 
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complex 95 
converting 78, See type conversion 
formatting 177-178 
inspecting 30, 102-110, See also Inspector 
windows 
problems with 77, 97, 153 
tracking 126 
variables and 322 
values 237 
setting breakpoints for 125 
viewing 166 
in recursive functions 77 
pointers to 786 
watching See Watches window 
Data menu 96-99, 196 
Data pane 174-179 
display formats 177-178 
local menu 175, 198 
memory addresses in 174 
pointer chains 176 
problems with, memory values 175 
Debug Information command 62 
Debugger command 62 
Debugger dialog box 62 
debugging 13-18, 165, See also programs, 
debugging 
80286 processors 253-255 
80386 processors 247-252 
80x86 processors 165-184 
assembler 
modules 171 
programs 165-184 
C++ programs See C++ programs, 
debugging 
continuous trace 85 
control 75-93, 139 
infinite loops and 89, 271 
interrupt vectors and 271, 273 
memory use and 80 
returning to Turbo Debugger 83, 89, 90 
symbol tables and 253 
TD386 virtual debugger and 257 
defined 13 
demo programs See demo programs 
device drivers 263-265 
problems with 262 
features 1, 17 
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functions 127, 129, 147 
recursive 77, 79 
hardware See hardware, debugging 
large programs 247 
display modes and 285 
problems with 307 
TDREMOTE and 295 
message logs and 27 
multi-language programs 9 
multiple components 50, 57 
object-oriented programs See object-oriented 
programs, debugging 
protected-mode See TD286 protected-mode 
debugger | 
remote systems 67, 299, See also TDREMOTE 
defaults, setting 290 
problems with 302, 311 
required files 2 
restrictions 15 
routines 274 
sessions 75 
preparing programs for 61-74, 232 
restarting 90-92 
starting 92 
simple programs 213 
small programs 66, 68 
source files and 2 
steps 14 
strategies 234, 239 
techniques 211-245 
terminology 2 
tools 15 
TSR programs 258-261 
tutorial 41-59, 232-245 
help with 42 
variables 214 
uninitialized 214 
virtual See TD386 virtual debugger 


debugging boards 117, 121, See also hardware 


compatibility with Turbo Debugger 77 
problems with 2717 
triggering breakpoints 127 


decimal numbers 72 


integers displayed as 153 


Decimal option (integer display) 72 
Decrement command 173 
Default Color Set command (TDINST) 282 
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default directories, changing 10 
default settings 279 
overriding 69, See also TDINST 
restoring 73, 293 
Delete All command 
Breakpoints menu 177 
Breakpoints window local menu 122 
Macros menu 70 
Watches window local menu 107 
demo programs 41-59, 232-245 
help with 42 
reloading 42 
source files 47 
starting 42, 234, 240 
Turbo C 45-52, 233-238 
Turbo Pascal 52-59, 238-245 
Descend command 
Inspector window local menu 172 
Object Data Field pane local menu 162 
descendant relationships 156, 157 
DesqView 251 
destructor methods 98 
problems with 314 
device drivers 261-262, See also hardware 
activating 265 
breakpoints and 120, 126 
problems with 327 
character vs. block 262 
debugging 263-265 
problems with 262 
virtual 257 
interrupt routine 262 
interrupts and 277 
loading 263 
strategy routine 262 
symbol tables, loading 264 
symbolic information, incorporating 263 
TDH386.SYS 77 
error messages 252 
installing 248 
TDREMOTE.EXE 296 
XMS 249 
dialog boxes 20 
bottom line in 39 
Breakpoint Options 719 
Change 78 
closing 74 
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commands and 303 
customizing 287 
Debugger 62 
Directories (TDINST) 286 
Display Options 77 
TDINST 283 
escaping out of 303 
Evaluate/ Modify 97, 137, 236, 241 
Expression Language 138 
icons 78 
Load Program 92 
messages 303-310 
Miscellaneous Options (TDINST) 289 
moving around in 20 
responding to 303 
Save Options 73 
search 133, 135 
Source Debugging (TDINST) 288 
Dialogs command (TDINST) 287 
directories 
default 10, 286 
paths 2 
multiple 67 
problems with 324 
setting 67, 72, 308 
TDREMOTE and 297 
Directories dialog box (TDINST) 286 
disassembled instructions 168 
disassembler 168 
display modes 777 
disk drives 262 
accessing, problems with 304 
running Turbo Debugger on two-floppy 2 
disks 
controllers 172 
distribution 7, 8 
files on See files, disk 
writing to, problems with 374, 375, 316 
display 
buffer, saving 285 
formats 
data types 177-178 
expressions 153 
integers 72, 177, 178, 284 
modes 281 
Code pane (CPU) 177 
controller registers 272 
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defaults, setting 70, 290 
problems with 11, 328 
ROM BIOS calls and 272 
options 283-286 
colors 280-282 
saving 36 
output 77 
problems with 297 
pages 285 
problems with 35 
swapping See screens, swapping 
updating 285 
Display As command 
Data pane local menu 174, 177 
File window local menu 136 
Display command (TDINST) 283 
Display Options command 70 
Display Options dialog box 77 
TDINST 283 
display pages 
multiple 65 
Display Swapping radio buttons 77 
TDINST 283 
distribution disks 7 
copying 8 
—do option (run on secondary display) 65 
DOS 


command processor, problems with 313 

COMSPEC environment variable 313 

debugging programs from 65 

device drivers and 267 

examining code inside 169, 175 

exit code and 87 

function calls 270 

interrupt handlers and TSR programs 258 

overwriting 270 

returning to 74 

running programs from 64, 272, 273 
TD286 protected-mode debugger and 254 
TD386 virtual debugger and 248, 2517 
TDREMOTE and 299 

shelling to 73 
display swapping and 286 

system calls, Turbo Debugger and 65 

tracing through 289 
problems with 270 
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TSR programs 
executing from 259 
versions 6, 80 
compatible with Turbo Debugger 7 
problems with TDCONFIG.TD and 69 
TD386 virtual debugger and 249 
TDREMOTE and 299 
wildcards, choosing files and 134 
DOS Shell command 73, 314 
TD286 protected-mode debugger and 254 
TDREMOTE and 299 
DOS Shell command, TD386 virtual debugger and 
250 
double colon (::) operator 146, 148 
Double command 178 
—dp option (use two display pages) 65 
drives See disk drives 
—ds option (swap screens) 65 
Dump command 183 
Dump Pane to Log command 123 
Dump window 28, 182 
local menu 200 
opening 183 
duplicate windows, opening 30 


-e option (TD386 virtual debugger) 249 
Edit command 314 
File window local menu 17, 136 
Module window local menu 133 
problems with 314 
Watches window local menu 107 
editing 
ASCII files 136 
expressions 107 
history lists 24 
editors, text See text editors 
EGA See also graphics adapters; video adapters 
line display 68, 72, 284 
palette 68 
Empty command 187 
EMS 80, 272 
disabling 272 
drivers 272 
emulation and TD386 virtual debugger 249 
enabling 289 
execution history and 86 
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problems with 370 

simulators 257 

symbol tables and 295 
emulator, 80x87 coprocessor 185 
end of lines, problems with 327 
Enhanced Graphics Adapters See EGA 
Erase Log command 124 
Erase Log File command 123 
error messages 370-328 

beep, enabling 287 

fatal 370 

TD386 virtual debugger 257-252 
errors, boundary See boundary errors 
escape sequences, Turbo C 145 
Evaluate command 337 
Evaluate input box 97 
Evaluate/Modify command 96-99, 137 
Evaluate/ Modify dialog box 97, 137 

using 236, 241 
executable program files See files 
Execute option (breakpoints action) 119 
Execute To command 84 
execution history 86, See also Execution History 

window 

backward trace and 87 

deleting 88 

losing 87 

recovering 87, 88, 89 
Execution History command 86 
Execution History window 29, 86-89 

keystroke recording and 288 

opening 86 

panes 86 
exit code, returned to DOS 87 
exiting 

TDINST 294 

Turbo Debugger 74 

TSR debugging and 265 
tutorial 42 

expanded memory specification See EMS 
Expression Language dialog box 138 
Expression True Global command 117, 125 
Expression True option (breakpoints condition) 

121 
Expression True radio button 125 
expressions 137-153 

complex 96 
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editing 107 
entering, problems with 314, 316, 321, 322, 
323 
argument lists and 317 
character constants and 318 
invalid characters and 327 
invalid variables and 326, 327 
memory areas and 324 
operators and 314, 316, 319 
evaluating 96-99, 236, 241 
functions in 157 
implied scope 142 
language conventions 138 
problems with 142, 311,312, 316, 327 
procedures in 157 
return values 305 
formatting 153 
problems with 378 
inspecting 30, 96, 112, 308, See also Inspector 
windows 
language options 738, 288 
pointing at 99 
return values 100, 137 
scope override 140, 142 
syntax 
TASM 151-153 
Turbo C 143-149 
Turbo Pascal 149-157 
undefined 107 
updating 707 
watching 99, 305, See also Watches window 
format specifiers and 97 
with side effects (C programs) 98, 148 
WORD entering 
problems with 322 
Extended command 178 
extended memory 247 
protected-mode debugging and 253 
TD386 virtual debugger and 248 
problems with 252 


F 


-f option (TD386 virtual debugger) 249 

Far Code command 176 

Fast Screen Update check box (TDINST) 285 
fatal errors 370 
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File command 
File window local menu 136 
Module window local menu 132 
View menu 134 
File menu 194 
File window 27, 134-136 
local menu 134, 200 
opening 132 
files See also File menu; File window 
ARC 10 
ASM 260, 264 
AUTOEXEC.BAT 6 
virtual debugging and 248 
compiler directives and 129 
compressed 10 
configuration See configuration files 
demo program 47 
disk 27, 129, 134 
history lists and 123 
problems with 375 
editing 133 
executable program 129, 307 
required for debugging 2 
TD386 virtual debugger and 249, 250 
handles 270 
HELPME!.DOC 7, 8 287 
include 129 
INSTALL.EXE 8, 10 
list boxes and 25 
loading See files, opening 
log 305 
problems with 372, 315 
saving entries to 286 
modifying, byte lists and 143 


moving to specific tine number in 132, 135 


multiple 
viewing 132, 136 
opening 92, 134, 306 
problems with 68, 315, 324 
wildcard masks and 327 
overriding 138 
overwriting 308 
PROGNAME.TDK 88 
reading to memory 179 
README 7, 8 10 
searching 135 
searching for 208 
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source See source files 
SWAP.$$$ 315 
TCDEMO.C 47 
TCDEMO.EXE 238 
TD.EXE 293 
TDCOMFIG.TD 36, 64, 69 
TDH386.SYS 11, 121, 248, 250 
TDREMOTE.EXE 296 
.TDS 260, 263, 264 
text 205, See also ASCIL, files 
THELP.COM 37 
TPDEMO.PAS 41, 245 
tracking 30 
unarchiving and unpacking 10 
viewing 27, 130, 134, 136 
as ASCII text 134, 136 
text editors and 136 
as hex data 134, 136 
offset address 306 
text editors and 136 
multiple 132, 136 
source code 130 
writing to, problems with 376 
filled arrow 45 
flags 
80x87 coprocessor 
control 187 
status 188 
CPU See CPU, flags 
Flags pane 167, 173 
local menu 174 
Float command 178 
floating point 
constants 
TASM 152 
Turbo C 145 
Turbo Pascal 150 
numbers 185 
formatting 153, 174, 178 
problems with 29 
registers 186, 306 
problems with 379 
Follow command 
Code pane local menu 169 
Data pane local menu 176 
Stack pane local menu 180 
format specifiers 97, 153 
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problems with 378 
repeat counts and 326 
Full Graphics Saving check box (TDINST) 285 
Full History command 88 
function keys 38, See also hot keys; keys 
summary of 791-193 
Function Return command 99, 330 
functions 2, See also specific language 
calling 99 
problems with 377, 318, 322 
class-member See C++ programs 
debugging 127, 129, 147 
inspecting 79, 111, See also Inspector 
windows 
variable with same name as 77 
method See object-oriented programs 
names, finding 27 . 
recursive, local data and 77, 79 
return values and current 99 
returning from 84, 170 
returning to 780 
stepping over 75 
stepping through 84 
variables and inactive 314 
viewing in stack 27, 79 
watching See Watches window 
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Get Info command 80 
Get Info text box 80 
global breakpoints See breakpoints 
Global check box 125 
global menus 78, See also menus 
local vs. 22 
reference 194-196 
Global pane 77 
local menu 77 
Global Symbol pane local menu 203 
global symbols 203 
disassembler and 168 
global variables See also variables 
changing 78 
debugging, in subroutines 214 
inspecting 77, See also Inspector windows 
same name as local 78 
viewing 27, 77 
in stack 27 
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Go to Cursor command 83 
Goto command 
Code pane local menu 769 
Data pane local menu 175 
File window local menu 135 
Module window local menu 733 
Stack pane local menu 780 
graphics 8 
adapters, monochrome text-only 291 
color tables 287 
display buffer, saving 285 
modes See display, modes 
palettes 68 
problems with 68 
snow 285 
graphics adapters 290, See also hardware 
CGA, problems with 71 
display options 297 
display pages 285 
EGA 68, 72, 284 
Hercules 291 
problems with 328 
supported 377 
VGA 68, 72, 284 


H 
~h option 
INSTALL 70 
-h option (help) 65 
TD386 virtual debugger 249 
TDREMOTE 298 
hardware 
adapters See graphics adapters; video 
adapters 
debugging 17, 117, 121, Seealso breakpoints, 
hardware-assisted 
problems with 82, 313, 327 
debugging boards See debugging boards 
keyboard interupts 277 
math chips 2, 168, 185 
peripheral device controllers 172 
primary and secondary displays 65 
requirements 7 
TD286 protected-mode debugger 253 
TD386 virtual debugger 248 
TDREMOTE 296 
Hardware Breakpoint command 117 
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Hardware option (breakpoints condition) 127 
Hardware Options command 127 
heap 
allocation 214 
size, setting 66 
help 36-39 
accessing 36 
problems with 317, 321 
additional topics for 37 
command-line options 65 
TD386 virtual debugger 250 
TDINST 293 
TDREMOTE 298 
Turbo Debugger utilities 9 
context-sensitive 36-39 
current activity 36 
demo programs 42 
dialog boxes 20 
language-specific 37 
online 36-38 
Help button 20 
Help Index 37 
Help menu 37, 197 
Help on Help command 37 . 
Help screen 
activating 37 
highlighted keywords in 37 
HELPME!.DOC 7, 8 
setting directory path for 287 
Hercules graphics adapter 2917 
Hex display option (files) 136 
Hex option (integer display) 72 
hexadecimal bytes 135 
floating-point registers 186 
viewing 
data as 175, 177 
files as 134, 136 
hexadecimal constants 
TASM 152 
Turbo Pascal 150 
hexadecimal numbers 72 
integers displayed as 153 
hierarchies, object type\class 155, See also 
Hierarchy window 
Hierarchy command 
Object Data Field pane local menu 159, 162 
Object Methods pane local menu 7160 
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View menu 155 


Hierarchy Tree pane 156, 157 


local menu 157, 202 


Hierarchy window 29, 155, 202 


opening 155 
panes 156-158 


highlight bar in windows 34 
History List Length input box (TDINST) 287 
history lists 23-24, See also execution history 


breakpoints 122 
editing 24 

length, setting 287 
logging to 123 
moving around in 207 


hot keys 79, See also keys 


Alt = (Create Macros) 70 

Alt — (Stop Recording) 70 
Alt-B (Breakpoints) 116 
Alt-F4 (Back Trace) 85 
Alt-F3 (Close) 35 

Alt-F9 (Execute To) 84 
Alt-F7 (Instruction Trace) 85 
Alt-F4 (Reverse Execution) 87 
Alt-F6 (Undo Close) 35 
Alt-F5 (User screen) 30 
Ctrl-F2 (Program Reset) 86 
Ctrl-F5 (Size/Move) 35 
Ctrl-I (Inspect) 27 

Ctrl-N (text entry) 24 

dialog boxes 20 

enabling 288 

F2 (Breakpoints) 47 

F4 (Go to Cursor) 83 

F3 (Module window) 26 

F6 (Next Window) 33 

F9 (Run) 83 

F8 (Step Over) 83 

F7 (Trace Into) 83 

F8 (Until Return) 84 

F5 (Zoom) 35 

help with 38 

local menus 23, 38 

macros as 25, 70 

summary of 191-193 
Tab/Shift-Tab (Next Pane) 33 
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~i option (enable ID switching) 65, 270 
IBM display character set 153 
IBM PC Convertible and NMI 9, 289 
iconize box 32 
Iconize/ Restore command 35 
icons 
dialog boxes 18 
menu 78 
reducing windows to 32, 35 
zoom 32 
ID switching See process ID switching 
identifiers 
program, handling 67 
referencing in other modules 139 
scope override 142 
Ignore Symbol Case check box (TDINST) 289 
In Byte command 172 
include files 129 
Increment command 173 
incremental matching 25 
Index command 37 
indicators, activity 36 
initialization code 332 
inline assembler keywords 275-278 
problems with 320 
input See I/O 
input boxes 20, See also dialog boxes 
Action Expression 179 
Address 127 
Condition Expression 120, 121 
entering text in 24 
Evaluate 97 
History List Length (TDINST) 287 
history lists and 23-24 
Log List Length (TDINST) 286 
Maximum Tiled Watch (TDINST) 284 
moving around in 207 
New Value 97 
Pass Count 1217, 124 
Result 97 
Save To 73 
Spare Symbol Memory (TDINST) 290 
Tab Size 72 
TDINST 284 
Inspect command 48 
Breakpoints window local menu 122 
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Data menu 30, 96 
Global pane local menu 77 
Hierarchy Tree pane local menu 157 
Inspector window local menu 177 
Instructions pane local menu 87 
Keystroke Recording local menu 88 
Module window local menu 137 
Object Data Field pane local menu 158, 159, 
162 
Object Methods pane local menu 160 
Object Type List pane local menu 156 
Parent Tree pane local menu 158 
Stack window local menu 79 
Static pane local menu 78 
Watches window local menu 107 
Inspector windows 16, 21, 30, 102-112 
arrays 104, 107, 109 
closing 30 
compound data objects and 96, 112 
functions 105, 108 
method/member 158 
global symbols and 77 
language-specific programs and 102 
local menus 177-112 
object/class instance 205 
object type/class 204 
local symbols and 78 
object/class instance 160-163 
object type/class 158-160 
opening 26 
additional 30 
panes 
object/class instance 160 
object type/class 158 
pointers 103, 106, 109 
problems with 
character values in 103, 106 
multiple lines and 104, 107, 109 
pointers to arrays 104 
procedures 108 
records 107 
reducing number onscreen 172 
scalars 103, 106, 108 
structures 105, 170 
unions 105, 110 
using 
C tutorial 48-50 
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in demo programs 235, 242 
Pascal tutorial 55-57 
variables in 77 
viewing contents as raw data bytes 102 
INSTALL.EXE 8, 70 
problems with graphics display and 11 
installation 10 
command-line options, help 10 
compressed (.ZIP) files and 10 
problems with, graphic display and 17 
TD286 protected-mode debugger 253, 254 
TD386 virtual debugger 248 
TDH386.SYS device driver 11, 248 
TDINST utility and See TDINST 
TDREMOTE 296 
instruction opcodes 186 
illegal 82 
instruction pointers, viewing 786 
Instruction Trace command 85 
execution history and 88 
instructions 165, See also Instructions pane 
assembling 166, 171, 180-182 
problems with 317, 318, 319, 320 
base and index registers 314, 319, 325 
instruction mnemonics 378 
invalid registers 320 
size indicators 324 
target addresses 314, 318 
referencing variables 187 
back tracing into 87 
breakpoints and 125, 126 
built-in assembler and 166, 181-182 
current interrupt 770 
disassembled 88 
divide, information about 82 
execution history and 86-88 
inspecting 87, See also Inspector windows 
machine 166 
executing 83, 85 
stepping through 766 
Turbo C compiler and 183 
multiple assembly treated as single 84 
referencing memory 167 
single-stepping 
interrupts and 271 
viewing 86 
coprocessor 186 
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watching See also CPU window; Watches 
. Window 
Instructions pane 86-88 
local menu 87 
Integer Format radio buttons 72 
TDINST 284 
integers 
constants 
TASM 152 
Turbo C 145 
Turbo Pascal 150 
formatting 72, 177, 178, 284 
viewing 
decimal 153 
hexadecimal 153 
watching 100, See also Watches window 
interrupt handlers 258 
Interrupt Key radio button (TDINST) 287 
interrupt routine 262 
interrupt vectors 271, 273 
loading 271 
interrupts 170 
back tracing into 86 
device drivers and 265 
exception, TD386 virtual debugger and 257 
handlers 
TSR programs 257 
keyboard 271 
NMI 9, 289 
problems with 87, 170 
program 89, See also Ctrl-Break (interrupt 
key) 
messages about 82 
TDREMOTE 297, 302 
software 257, 258 
tracing into 85 
TSR programs and 259 
1/O 
CPU 172 
functions, low-level 267 
options 287 
ports 172 
reading from 307 
writing to 307 
TDREMOTE and 299 
video 77 
watching, TD386 virtual debugger and 247 
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1/O command 172 


K 


-k option (enable keystroke recording) 65 
keyboard interrupt 277 
keys See also arrow keys; function keys; hot 
keys 
assigning as macros 25, 70 
Ctrl-Break (interrupt) 81, 89, 287 
cursor-movement 34, 208 
CPU window 167 
dialog boxes 20, 207 
Help window 37 
menu commands 19 
TDINST 280 
text boxes 206 
text files 206 
recording as macros See keystrokes, 
recording 
keystroke macro facility 91 
Keystroke Recording check box (TDINST) 288 
Keystroke Recording pane 88 
local menu 88 
Keystroke Restore command 89 
keystrokes 
assigning as macros 25, 70 
displayed 29 
recording 65, 91, 326 
automatic 288 
execution history and 86, 88 
problems with 304 
restoring to previous 70 
replaying 88 
keywords, inline assembler 275-278 
problems with 320 
keywords in Help window 37 


L 


-l option (assembler mode) 66 
labels, running programs to 84 
tutorial 46, 53 
Language command 138 
Language radio buttons (TDINST) 288 
language-specific applications See also specific 
language 
assignment operators and 78 


Index 


conventions 738 
debugging 215-231, 329-334 
preparing for 61-63 
expressions and 137 
help with 37 
Inspector windows and 102 
options 284, 288 
scope override and 140 
using 15, 137 
Layout option (save configuration) 73 
layouts 
restoring 35, 36 
LCD screens 297 
problems with 77 
license agreement, Borland 7 
Line command 132 
line numbers 306 
Code pane 168 
displaying current 45 
generating scope override 140 
moving to specific 132, 135 
problems with, source files and current 137 
lines, multiple, problems with 104, 107, 109 
Link Speed radio buttons (TDINST) 290 
linked lists 112 
list boxes 20, See also dialog boxes 
incremental matching in 25 
moving around in 206, 207 
list panes, Pick a Module 129 
lists, choosing items from 34 
Load Program dialog box 92 
local menus 22-23, See also menus 
accessing 22 
Breakpoints window 118-122, 197 
Code pane 169-172, 198 
Control pane 187, 202 
Data pane 175-179, 198 
Dump window 200 
File window 134-136, 200 
Flags pane 174 
Global pane 77 
Global Symbol! pane 203 
Hierarchy Tree pane 157, 202 
Inspector windows 111-112, 204 
Instructions pane 87 
Keystroke Recording pane 88 
Local Symbol pane 203 


357 


Log window 123, 200 
Module window 131-133, 201 
Object Data Field pane 159, 167 
Object Method pane 160, 162 
Object Type/Class List pane 156, 202 
Parent Tree pane 158, 202 
Register pane 
CPU window 173-174, 199 
Numeric Processor window 187, 201 
Registers window 202 
Stack pane 179-180, 200 
Stack window 79, 203 
Static pane 78 
Status pane 188, 202 
Varibles window 203 
viewing hot keys in 38 
Watches window 101, 203 
Local Symbol pane local menu 203 
Local Symbols command 62 
local variables See also variables 
breakpoints and 178 
changing 78 
global values and 77 
inspecting 78, See also Inspector windows 
problems with 327 
viewing 27 
in stack 27 
specific instances of 77, 79 
Locals command 77, 79 
Log command 122 
log files 305 
opening, problems with 372, 315 
saving entries to 286 
writing to, problems with 315 
Log List Length input box (TDINST) 286 
Log option (breakpoints action) 120 
Log radio button 127 
Log To File command 315 
Log window 27, 122-124 
adding comments to 305 
local menu 123, 200 
opening 122 
Logging command 123 
Long command 177 
loops, infinite 271 
problems with debugging and 89 
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M 


~m option (set heap size) 66 
machine instructions 166 
executing 83, 85 
stepping through 166 
Turbo C compiler and 183 
macros 25 
recording 25 
keystrokes as 70, 97 
problems with 308, 315, 326 
terminating 25 
removing 70 
restoring to previous 70 
saving 73, 91 
to configuration files 97 
Macros command 25, 70 
Macros option (save configuration) 73 
MASM See Microsoft languages 
math chips 2 
80x87 coprocessor 185 
disassembler and 168 
math coprocessor See numeric coprocessors 
Maximum Tiled Watch input box (TDINST) 284 
memory 68, 285, 295 
accessing 
problems with 175 
TD386 virtual debugger and 257 
addresses 137, 270, 306 
disassembler and 167 
symbolic 168 
dump 174 
entering 306 
high 247 
Numeric Processor window 186 
problems with 320 
references vs. 187 
allocation 74, 272 
inspecting 80 
problems with 74, 214, 323 
TD386 virtual debugger and 248 
allocation for symbol tables 
device drivers and 263 
TSR programs and 260 
blocks 272, 304 
manipulating 178 
problems with 315 
buffer 262 


Turbo Debugger User's Guide 


device drivers and 262 
dump 28, 174-179, 182 
problems with 175 
extended See extended memory 
freeing 253, 269 
graphics mode and 68 
heap size and, problems with 66 
interrupt vectors and 273 
locations 270 
problems with 316, 324 
symbol tables and 261, 264 
mapping 80 
device drivers and 263 
TSR programs and 259, 260 
operands, problems with 374 
problems with 323 
random access See RAM 
read-only 169, 175, 313 
references 
built-in assembler 787 
formatting 153 
problems with 322 
symbol tables and 68, 290 
tracking 126 
watching 120 
specific areas of 125 
TD386 virtual debugger and 247 
menu bar 78, 43 
activating 78 
commands 194 
menu trees 208-209 
menus 78-19 
= (System) 18, 194 
activating 78 
Breakpoints 1716, 195 
commands See commands 
customizing 281, 282 
Data 96-99, 196 
exiting 19 
File 194 
global 18 
local vs. 22 
reference 194-196 
Help 37, 197 
hot keys and 719 
local See local menus 
Options 69-73, 196 
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pop-up 78 
pull-down 78 
Run 75, 82-85, 195 
program termination and 90 
TDINST 280 
tutorial 43 
View 26, 194 
Window 33, 45, 196 
Menus command (TDINST) 282 
message log 27, See also log files 
messages See also error messages 
dialog boxes 303-310 
informational 328 
program termination 87 
TDREMOTE 300-302 
methods See functions; object-oriented 
programs 
Methods command 167 
Microsoft 
languages, Turbo Debugger and 7, 15 
MASM, Quirks mode 237 
Windows 257 
Miscellaneous Options dialog box (TDINST) 
289 
Mixed command 168, 171 
Mode for Display menu (TDINST) 290 
modes See display modes 
Modify TD.EXE command (TDINST) 293 
Module command 321 
Module window local menu 132 
View menu 730 
Module window 26, 130-133 
filled arrow and 45 
local menu 137, 201 
opening 130 
duplicate 132 
program execution and 82-89 
source files and 130 
modules 2, 129, See also Module window 
assembler 177 
compiling 67 
current, overriding 138 
hierarchy tree (object/class types) 29 
high-level source 777 
language options 288 
loading 130, 309 
new 132 
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problems with 133 
referencing identifiers in other 139 
scope override and 101, 140 
tracing into 85 
tracking 30 
viewing 26, 130-133 
duplicate 132 
problems with 321, 322, 326 
source code in 306 
modulus operator, problems with 314 
monitors See also hardware; screens 
color 65, 2917 
customizing 280-282 
compatible with Turbo Debugger 7 
composite 17 
customizing color tables 2817 
display options 290 
display swapping 65, 286 
monochrome 65 
problems with 717 
problems with 17 
monochrome monitors See monitors, 
monochrome 
mouse 
choosing menu commands 18-19 


executing Alt- or Ctrl-key commands 39 


moving around in dialog boxes 20 
setting breakpoints 47, 116 
support 
disabling /enabling 66, 287 
online help 37 
windows and 31-32 
Mouse Enabled check box (TDINST) 287 
Move command 179 
multi-language programs 9 
multiple inheritance 29, 156, 157 


N 


Near Code command 176 

NEC MultiSpeed and NMI 9, 289 

New CS:IP command 177 

New Expression command 
Inspector window local menu 112 
Object Data Field pane local menu 162 

New Value input box 97 

Next command See also Search command 
Data pane local menu 176 
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File window local menu 136 
Module window local menu 133 
problems with 327 
Next Pane command 33 
Next Window command 33 
NMI, systems using 9, 289 
NMI Intercept check box (TDINST) 289 
None option (display swapping) 77 
nonmaskable interrupt See NMI 
nonprinting characters 103, 106 
return value 153 
null modem cable 296 
null-terminated character string 103, 109 
numbering system, windows 33 
numbers 99 
decimal 72 
floating-point See floating point, numbers 
formatting 153, 284 
problems with 316 
TASM 152 
Turbo C 145 
Turbo Pascal 150 
hexadecimal 72 
real 150 
scalar 143 
numeric coprocessors See also 80x87 
coprocessors 
changing 185-189 
control flags 187 
current state, viewing 29 
data size overrides 182 
disassembler and 168 
instructions 
assembling 780-182 
mnemonics 278 
registers 186, 277 
entering new values for 306 
status flags 188 
numeric exit code 87 
Numeric Processor command 786 
Numeric Processor window 29, 186-189 
opening 186 
problems with 327 
panes 186, 207 


O 


-O- option (TCC) 62 
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Object Data Field pane 158 
local menu 159, 167 
Object Method pane 158 
local menu 160, 162 
object methods See functions; object-oriented 
programs 
object modules 129 
object-oriented programs 
compatibility with Turbo Debugger 155 
debugging 76, 155-163 
nested object structures 758 
Self parameter and 107 
Self/this parameter and 97 
expressions, problems with 312 
object hierarchies 156 
object instances 
formatting 97 
inspecting 160-163 
object methods 29, 79 
inspecting 158 
problems with 374 
tracing into 83 
object types 
hierarchy tree 29 
inspecting 158-160 
scope override 141 
stepping through single statements 84 
Object Type/Class List pane, local menu 156 
Object Type List pane 756 
local menu 202 
objects, data See data, objects 
Offset to Data command 176 
online help 36-38, See also help 
dialog boxes 20 
OOP See object-oriented programs 
opcodes, illegal instruction 82 
Open command 92 
Open Log File command 122, 123 
operands 99, 316 
instruction, memory pointers and 167, 187 
problems with 324 
invalid 379 
invalid separators and 319 
out of range 377 
segment overrides and 373 
size 168 
problems with 324 


Index 


size overrides 181, 182 
operators 376 
assignment See assignment operators 
binary 146, 150 
C programs and 98 
invalid 319 
modulus, problems with 314 
OFFSET (built-in assembler) 787 
precedence 
TASM 152 
Turbo C 146 
Turbo Pascal 150 
options 69, 286, See also Options menu 
command-line See command-line options 
customizing 279 
display 283-286 
display swapping 77, 283 
input 287 
language 284 
expressions 288 
program execution 82 
restoring defaults 73, 293 
saving 72 
Options menu 69-73, 196 
TDINST 286 
Options option (save configuration) 73 
Origin command 80 
Code pane local menu 169 
Module window local menu 133, 142 
Stack pane local menu 780 
Out Byte command 172 
output See also I/O 
display onscreen 77 
overlays 
pool size 68 
problems with 324 
protected-mode debugging and 254 


Pp 


—p option (mouse support) 66 
panes 
blinking cursor in 34 
Breakpoints window 26, 118 
Code See Code pane 
Control 187 
CPU window 28 
cycling through 167 
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Data See Data pane 
Execution History window 29, 86 
Flags 167, 173, 174 
Hierarchy window 29, 156-158 
highlight bar in 34 
Inspector windows 30 
object/class instance 160 
object type/class 158 
list boxes 206 
local menus and 22 
moving between window 33 
Numeric Processor window 29, 186, 201 
recording current contents of 123 
Register 
CPU window 173-174 
Numeric Processor window 186-187 
Registers window 28 
Stack 167, 179-180 
Status 188 
text See text panes 
Variables window 27, 77 
parameters 2, See also arguments 
logging 127 
Self 97, 107 
this 97 
viewing, program-calling 79 
Parent Tree pane 157 
local menu 158, 202 
Parents command 157 
parsing, Turbo Debugger vs. Turbo languages 9 
Pascal option (language convention) 738 
Pascal programming language See Turbo Pascal 
Pass Count input box 121, 125 
pass counts 715 
decrementing 127 
problems with 319 
setting 121, 124, 125 
Path for Source command 2, 72 
paths, directory See directories 
Periscopy debugging board 71 
Permit 43/50 Lines check box (TDINST) 285 
Pick a Module list pane 129 
pointers 153, 176-177 
compound data objects 99 
current instruction 186 
memory 139, 167, 181 
stack, current location 167 
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pointing at data objects 99 
polymorphic objects 167 
pop-up menus 78 
orts 
I/O 172, 307 
remote link 67 
serial 67, 290 
precedence, operators See operators 
Previous command 37 
Code pane local menu 170 
Data pane local menu 177 
Module window local menu 132 
Stack pane local menu 180 
primary display 65, See also screens, swapping 
printers, problems with 304 
procedures See also functions; specific language 
calling, problems with 317 
stepping over 15 
viewing in stack 79 
process ID switching 65, 270, 289 
processors See 80x86 processors; CPU 
PROGNAME.TDK 88 
Program Reset command 86, 90, 97 
programs 67, 232, 286 
accuracy testing 237 
altering 27, 187 
breaking out of 9 
compiling 77 
current location 45, 157 
CPU window 167 
Inspector windows 78 
Module window 79 
problems with 86, 137 
returning to 80, 133, 142, 169 
scope 142 
overriding mechanism and 100 
setting 177 
stack 180 
verifying 30 
watching 85, 129, See also Watches 
window 
current state 76 
inspecting 76-82, See also Inspector 
windows 
debugging 15, 16, 61-64, 124, 211-212, See 
also debugging 
current scope and 142 
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infinite loops and 89, 271 
interrupt vectors and 277 
using 271, 273 
planning for 74, 232 
problems with 
disassembler and 172 
memory allocation and 74 
returning information on 80-82 
starting Turbo Debugger 63 
with no debug information 85, 325 
with out-of-date debug information 325 
demo See demo programs 
execution 8, See also programs, running 
controlling 75-93 
interrupting 89 
menu options 82 
problems with 817, 82 
reversing 85, 87, 88 
problems with 88 
terminating See programs, stopping 
fatal errors and 370 
full output screen 30 
incremental testing 213 
inspecting 27, See also Inspector windows 
interrupt key, resetting 90, 287 
language options 284, 288 
overriding 138 
language-options See also TDINST 
loading 247, 272, 307, See also files, opening 
load address, changing 269 
memory allocation and 272 
new 92 
problems with 68, 295, 315, 322, 325 
symbol tables and 323 
remote systems 298, See also TDREMOTE 
message logs and 27 
modifying See programs, altering 
multi-language 9 
opening See programs, loading 
patching, temporarily 766 
recompiling 17 
recovering 65, 87 
from crashes 97 
keystroke recording and 88, 917 
to a previous point 88 
reloading 86, 90 
problems with 315 
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restarting a debugging session 90, 97 
returning from 46, 53 
returning to 80, 132 
running 29, 75, 92, See also programs, 
execution 
to breakpoints 47, 54 
command-line options and 93 
to cursor 46, 52, 83 
DOS level, from 64, 251 
execution history and 86-89 
from DOS 254, 299 
at full speed 83 
to labels 46, 53, 84 
nonmaskable interrupts and 289 
returning information on 80 
in slow motion 85 
scope See scope 
source code See code 
source files and 130 
stepping through 166 
problems with 82 
tutorial 46, 53 
stopping 90, 116, 118, Seealso breakpoints 
at specific locations 125 
messages about 87 
swapping to disk 74 
problems with 374 
terminate and stay resident See TSR 
programs 
text-based 8 
watching See Watches window 
with floating-point numbers 785, 270 
prompts, setting 287 
protected-mode debugging See TD286 
protected-mode debugger 
pseudovariables (Turbo C) 144 
pull-down menus 78 


Q 


QuarterDeck EMS simulator 257 
Quit command 74 
TDINST 294 


R 


-r option (remote serial link) 67 
radio buttons 20, See also dialog boxes 
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Action 119 
Beginning Display (TDINST) 284 
Changed Memory 125, 126 
changing settings 20 
Condition 120 
Display Swapping 77 
TDINST 283 
Expression Language 138 
Expression True 125 
Integer Format 72 
TDINST 284 
Interrupt Key (TDINST) 287 
Language (TDINST) 288 
Link Speed (TDINST) 290 
Log 127 
Remote Link Port (TDINST) 290 
Screen Lines 72 
TDINST 284 
Source Debugging 62 
User Screen Updating (TDINST) 285 
RAM 
requirements, Turbo Debugger 7 
resident utilities 169, 175 
running Turbo Debugger as 259, 265 
problems with 373 
system map 259, 260 
TSR programs and 257 
segment containing 267 
Range command 
Inspector window local menu 117 
Object Data Field pane local menu 167 
range errors 225 
Read command 179 
read-only memory See ROM 
Read Word command 172 
README file 7, 8 710 
READY indicator 24 
Realcommand 178 
RECORDING indicator 70 
records, problems with 323, 327 
recursive functions 77, 79 
reference line 
dialog boxes 39 
Register pane 
CPU window 173-174 
local menu 173, 199 
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Numeric Processor window 186-187 
local menu 187, 2017 
registers 702, See also Registers window 
80386 processor, virtual debugging and 257 
80x87 coprocessors 186, 186-189 
assembling See Turbo Assembler 
valid address combinations 320 
CPU See CPU, registers 
display controller 272 
floating-point 186, 306 
problems with 314, 325 
invalid 319, 320 
segment 90, 153 
values, accessing 28, 183 
Registers 32-bit command 174 
Registers window 28, 183 
local menu 202 
panes 28 
release codes 271 
Relocate Table command 265 
remote debugging See TDREMOTE 
Remote Debugging check box (TDINST) 290 
remote file transfer utility (TDRF) 296, 299 
REMOTE indicator 299 
Remote Link Port radio buttons (TDINST) 290 
remote links 67 
defaults, setting 290 
hardware requirements 296 
maximum speed 297 
problems with 301, 309 
reducing link speed 302 
using 297-298 
remote systems See communications, remote 
systems 
Remove command 
Breakpoints window local menu 122 
Macros menu 70 
Watches window local menu 107 
Repaint Desktop command 35 
repeat counts 153 
problems with 326 
Resident command 259, 265 
resize box 32 
resizing windows See windows, resizing 
restarting a debugging session 90, 90-92 
Restore Options command 36, 73 
Restore Standard command 35 
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Result input box 97 
return values 127, 137 
bytes 176 
changing 701, 171 
CPU flags 174 
CPU registers 173, 183 
expressions 305 
inspecting 99, See also Inspector windows 
memory blocks 179 
nonprinting characters 153 
problems with 81, 175, 320, 328 
assignment 372 
tracking 100 
variables See variables 
Reverse Execute command 87 
reversing program execution 85, 87, See also 
backward trace 
problems with 88 
ROM 
accessing 169 
examining 175 
programs executing in 373 
routines 127, See also functions 
accessing 139 
problems with 308 
debugging 274 
testing 237 
viewing in stack 79 
-rp option (remote link port) 67 
TDREMOTE 298 
-rs option (remote link speed) 67 
TDREMOTE 297, 298 
Run command 83 
execution history and 88 
Run menu 75, 82-85, 195 
program termination and 90 
running 
programs See programs, running 
TD286 protected-mode debugger 253-255 
TD386 virtual debugger 247-252 
TDINST 279-294 
TDREMOTE 297-298 
Turbo Debugger 130 
as RAM resident program 259, 265 
problems with 373 
on two-floppy systems 2 
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S 


sample programs See demo programs 
Save Configuration check box 73 
Save Configuration File command (TDINST) 
293 
Save menu (TDINST) 293 
Save Options command 36, 72 
Save Options dialog box 73 
Save To input box 73 
—sc option (ignore case) 67 
scalar numbers 143, 305 
scalar variables 103, 106 
scientific notation 145, 152, 178 
scope 100, 139-142 
breakpoint expressions 178 
current 139, 142 
accessing symbols outside 139 
implied, evaluating expressions and 142 
overriding 140-142, 149 
problems with 316 
inactive 374 
Self parameter 97 
this parameter 97 
Screen command (TDINST) 282 
Screen Lines radio buttons 72 
TDINST 284 
screens See also hardware; monitors 
background, customizing 282 
colors, customizing 280-282 
display modes See display, modes 
layouts, restoring 35 
LCD 291 
lines per, setting 68, 72, 284, 285 
problems with 
graphics display 35, 68, 272 
and INSTALL 177 
snow 285 
writing to 77 
repainting 285 
startup 42 
options 284 
swapping 71, 283, 286 
multiple display pages and 65 
problems with 257, 254 
updating 285 
User See User screen 
scroll bars 32 
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scrolling 37 
dialog boxes 207 
Help screens 37 
Inspector windows 49, 56 
menus 79 
text boxes 206 
text panes 206 
-sd option (set source directories) 67 
Search command See also Next command 
Code pane local menu 170 
Data pane local menu 175 
File window local menu 135 
history lists and 23 
Module window local menu 132 
search templates 208 
secondary display 65, See also display, 
swapping 
segment 
overrides, problems with 313 
pointers to register 753 
PSP, problems with 370 
segment:offset addresses 
physical addresses and 186 
Segment:Offset to Data command 177 
segment registers, program termination and 90 
select by typing 25 
Self parameter 97 
watching 107 
serial cards 172 
serial links, remote 290, See also WORD 
communications, remote systems 
debugging over 67 
TDREMOTE and 297 
Set command 179 
Set Options command 119 
shelling to DOS 73 
shortcuts See hot keys 
Show Inherited command 
Object Data Field pane local menu 159, 162 
Object Methods pane local menu 160 
SideKick 257 
Size/Move command 35 
—sm option (set symbol table memory size) 67 
device drivers and 264 
TSR debugging and 260, 267 
Smart option (display swapping) 77 
snow 285 
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software 
emulator 168, 185 
changing 185-189 
using 270 
requirements 2 
source code See code 
Source Debugging dialog box (TDINST) 288 
Source Debugging radio button 62 
source files 2, 129-136, See also files 
language conventions and 138 
loading 130, 309 
problems with 322, 326 
setting directory path 287 
Source option (language convention) 138 
Spare Symbol Memory input box (TDINST) 290 
stack 90, 165, 166, See also Stack pane; Stack 
window 
current state 27, 79-80 
examining 179-180 
pointer, current location 167 
Stack command 77, 79 
Stack pane 179-180 
current stack pointer 167 
local menu 179, 200 
Stack window 27, 79-80 
local menu 79, 203 
opening 77, 79 
Standalone Debugging command 62 
standalone linkers 62, 63 
Standalone option 62 
starting Turbo Debugger 63 
in assembler mode 66 
command-line options and 267 
remote systems 297 
problems with 290 
startup screen 42 
options 284 
Static pane 77 
local menu 78 
static symbols, disassembler and 168 
status bits, viewing 788 
status flags 188 
status line 36, 38 
Status pane 188 
local menu 188, 202 
Step Over command 83, 332 
execution history and 88 
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stepping over 
functions 15 
procedures 715 


stepping through See also specific language 


application 
functions 84 
programs 166 
problems with 82 
Stop Recording command 25, 70 
strategy routine 262 
strings 753, 182 
byte lists and 143 
character 
null-terminated 703, 109 
quoted 735 
problems with 327 
searching 132, 133, 135, 136 
searching for 175, 176, 307 
Turbo C 145 
Turbo Pascal 150 
concatenation (Turbo Pascal) 149 
format control See format specifiers 
text, searching for 23 
truncated 97, 100 
structures 
changing 313 
inspecting complicated data 96, 112 
problems with 323, 327 
subdirectories, default 10 
subprograms See functions; routines 
subroutines, calling 170 
problems with 170 
SuperKey 257 
SWAP.$$$ 315 
switches See command-line options 
Symbol Load command 260, 264 
symbol names, problems with 312 
Symbol pane 27 
symbol tables 138, 261, 264, 325 
base segment address 307 
device drivers and 262 
invalid 325 
loading 308 
problems with 323, 326 
memory allocation 289, 295 
device drivers and 263 
setting 67, 290 
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TSR programs and 260 
TD286 protected-mode debugger and 253 
symbols 77, 137 
accessing 139-142, 309 
in other scopes 149 
as memory reference 187 
disassembler and 168 
global 203 
problems with 313, 326, 327 
invalid 320 
type information and 322 
scope 139 
Turbo C 143 
Turbo Pascal 149 
syntax 
checkers, built-in 75 
errors 15, 326 
system 
crashes 90, 171, 270 
recovering from 97 
rebooting 89 
System menu See = (System) menu 


T 


Tab Size input box 72 
TDINST 284 
Table Load command 68, 307 
Table Relocate command 267 
tabs, setting 72, 284 
problems with 328 
TAEXAMPLx.ARC 10 
Tandy 1000A and NMI 9, 289 
TCDEMO.C 41 
TCDEMO.EXE 238 
TD286 protected-mode debugger 253-255 
command-line options 254 
installation 254 
system requirements 253 
instructions 257 
running programs, problems with 254 
starting 254 
TD386 virtual debugger 247-252 
command-line options 249 
syntax 250 
error messages 251-252 
exception codes 82 
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installation 
device driver 11, 248 
system requirements 248 
problems with 257, 310 
setting breakpoints 1217 
starting 248 
problems with 257 
TD286INS 254 
TD.EXE 293 
TDCONFIG.TD 36, 69 
loading 64 
overriding 69 
TDDEV 259 
TDEXAMPL.ZIP 10 
TDH386.SYS 11, 121, 248, 250 
error messages 252 
TDINST 279-294 
command-line options vs. 2971-293 
exiting 294 
main menu 280 
options, saving 293 
TDMEM 259, 260 
TDREMOTE 295-302 
command-line options 298-299 
saving 299 
hardware requirements 296 
messages 300-302 
problems with 377 
running 297-298 
problems with 309 
software requirements 296 
TDREMOTE.EXE 296 
TDS files 260, 263, 264 
technical support, Borland 5 
terminate and stay resident See TSR programs 
ternary operators (Turbo C) 147 
text 72 
editing See Edit command; editing 
entering 
active windows and 37 
in input boxes 24 
incremental matching 25 
in log 305 
searching for 208, 326 
strings, searching for 23 
text-based programs 8 
text boxes, Get Info 80 
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text editors 133, 136, 286 
compatibility with Turbo Debugger 16 
problems with 314 

text files 205, See also ASCII, files 

text modes See also display, modes 
problems with 77 

text panes 205, 305, 308, 314 
moving around in 206 

THELP.COM 37 

this parameter 97 

tiled windows 44, 284 

time delays, setting 85, 304 

Toggle command 
Breakpoints menu 117, 124 
Control pane local menu 188 
Flags pane local menu 174 
Status pane local menu 188 

TPDEMO.PAS 41, 245 

Trace Into command 83, 332 
continuous tracing 85 
execution history and 88 
programs executing in ROM and 373 

tracepoints 115, See also breakpoints 

tracing 15, 86-89, See also Trace Into command 
backward See backward trace 
continuous (animation) 85, 304 
execution history and 86 
information about 87 
into interrupts 85 
into functions 45, 52 
Self parameter and 97, 107 
this parameter and 97 

Tree command 157 

TSR programs 74 
debugging 258-261 

resident portion 258, 259 

transient portion 257 
display swapping and 286 
executing from DOS 259 
resident portion 257, 259 
symbol tables, loading 260 
transient portion 257, 258 

Turbo Assembler See also assembler 

arrays 

inspecting 709 
bugs specific to 226-231 
built-in assembler vs. 187-182 
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code, stepping through 337 
command-line options 63 
conditional jumps 228 
constants 152 
data, inspecting 108-110 
debugging techniques 165-184 
example program files 10 
expressions 151-153 
assignment 337 
flags altered by instructions 230 
functions 
returning from 227 
functions, returning from 226 
hex data, examining 337 
INCLUDE compiler directive 129 
instruction mnemonics 168, 169 
size overrides 187, 182 
instructions See also instructions 
carry flags and 230 
mnemonics 275-278 
string 228 . 
byte to word conversions 229 
comparisons 229 
direction flags and 228 
multiple prefixes 229 
operands to 229 
registers, altered 230 
segment defaults and 229 
interrupt handlers 230 
machine code bytes, viewing 337 
operands 
memory variables and 230 
order of 227 
operators, precedence 152 
pointers 
inspecting 709 
programs 331-332 
debugging 226 
preparation for 63 


Quirks mode, using MASM and 237 


registers 
multiplication and 229 
preserving 227 
saved in interrupt handler 230 
viewing 337 

registers, altering 337 

scalars, inspecting 108 
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segment groups 237 
segment wraparound 230 
stack allocation 227 
structures, inspecting 170 
symbols 157 
unions, inspecting 170 
variables 
immediate operands vs. 230 
versions compatible with Turbo Debugger 2 
Turbo C 215, 316, See also C++ programs 
arrays 50, 216 
inspecting 104 
problems with 104 
autovariables 218, See also variables herein 
scope 278 
uninitialized 275 
bugs specific to 215-219 
character strings 145 
code 
stepping through 329 
tracing into 45 
command-line options 62 
compiler 183, 215 
directives, #include 129 
optimizing 329 
constants 145 
CPU registers, use of 183 
data 
inspecting 103-106 
types 48-49 
compound 50 
converting 148 
debugging techniques 329-331 
preparing programs for 62 
demo programs 41, 45-52 
debugging 233-238 
starting 42 
escape sequences 145 
expressions 143-149, 216 
complex, stepping through 330 
entering in dialog boxes 57 
problems with 377 
with side effects 98, 148 
#define macros and 218 
functions 46, 147, 330 
inspecting 705 
problems with 98 
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returning from 46, 218 
tracing into 45 
integer assignment 277 
keywords 148 
problems with 320 
language-specific help 37 
loops, exiting 279 
operators 276 
expressions with side effects and 98, 148 
precedence 146, 216 
optimization 62 
pointers 330 
incrementing and decrementing 276 
inspecting 103 
pseudovariables 144, 145, See also variables 
herein 
scalars, inspecting 103 
source code 217, 219 
source files 42 
structures, inspecting 105 
symbols 143 
Transfer utility 77 
unions, inspecting 105 
variables See also autovariables; 
pseudovariables herein 
inspecting 48-50 
return values 50-52, 100 
watching 48 
versions compatible with Turbo Debugger 2 
Turbo Pascal See also object-oriented programs 
arrays 57 
inspecting 107 
bugs specific to 219-226 
code 
skipping over 332 
stepping through 332 
tracing into 52 
command-line options 62 
compiler directives 
$B option 221, 226 
$R option 225 
constants 150, 332, 334 
data 
inspecting 106-108 
types 55-56 
compound 57 
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converting 333 
debugging techniques 332-334 
preparing programs for 62 
Variables window and 76 
demo programs 47, 52-59 
debugging 238-245 
starting 42 
expressions 149-157 
entering in dialog boxes 58 
functions 151, 317, 333 
executing 53 
inspecting 108 
returning from 53, 223 
tracing into 52 
language-specific help 37 
operators 149, 333, 334 
precedence 150 
pointers 220 
inspecting 106 
procedures 1517, 317 
inspecting 108 
stepping through 332 
range-checking 225, 334 
records, inspecting 107 
routines, watching 334 
scalars, inspecting 106 
source code 67, 222 
source files 42 
strings 150, 333 
concatenation 149 
symbols 62, 149 
units See also modules 
override syntax 7141 
variables 220, 221 
decrementing 224 
inspecting 55-57 
problems with 312, 328 
return values 57-59, 100 
watching 54, 333 
versions compatible with Turbo Debugger 2 
two-floppy systems, Turbo Debugger on 2 
type conversion 78, 107 
problems with 320, 327 
Turbo C reserved words and 148 
Turbo Pascal 333 
typecasting See type conversion 
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types 
class member See C++ programs 
data See data, types 
object See objects, types 
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unarchiving example files 70 
unary operators 
Turbo C 146 
Turbo Pascal 150 
Undo Close command 35 
union members, problems with 323 
Until Return command 84 
UNZIP.EXE utility 70 
Use Expanded Memory check box (TDINST) 
289 
User screen 30, 71 
display buffer 285 
updating 285 
User Screen command 30 
remote links and 299 
User Screen Updating radio buttons (TDINST) 
285 
utilities 
disk-based documentation for 9 
INSTALL 10 
problems with graphics display and 17 
TDINST See TDINST 
TDREMOTE See TDREMOTE 
TDRF (remote file transfer) 296, 299 
THELP 37 
UNPACK 10 


V 
/v option 
TLINK 62, 63 
TPC 62 
~v option (TCC) 62 
values, return See return values 
variables 27, 96-99, See also Variables window 
accessing 139 
problems with 317 
with no type information 148 
built-in assembler and 187 
debugging 214 


Index 


global See global variables 
inactive functions and 374 
inspecting 30, 96, 102-110, 112, 308, See also 
Inspector windows 
function with same name as 77 
in recursive functions 79 
language conventions and 138 
local See local variables 
logging 127 
multiple 127 
names 100 
finding 27 
problems with 322 
pointing at 99 
private 107 
program termination and 90 
return values 16, 98 
inspecting 30 
problems with 77, 103, 106 
scalar, character values and 103, 106 
scope override 140 
uninitialized 214 
updating 707 
viewing 76-78 
in recursive functions 77 
watching 26, 99, 100, 305, See also Watches 
window 
Variables command 77 
Variables window 27, 76-78 
local menu 203 
opening 77 
vectors, interrupt See interrupt vectors 
-vg option (save graphics image) 68 
VGA See also graphics adapters; video adapters 
line display 68, 72, 284 
video adapters 172, 290, See also graphics 
adapters, hardware 
command-line options 68 
display options 72 
setting 284, 285 
display pages 285 
problems with 328 
supported 371 
Video Graphics Array Adapter See VGA 
videos See monitors; screens 
View menu 26, 194 
virtual debugging See TD386 virtual debugger 
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virtual methods table (VMT) 767 
-vn option (no EGA/VGA display) 68 
—vp option (EGA palette save) 68 


W 
—w option 
TD386 virtual debugger 250, 252 
TDREMOTE 298 
warning beeps, enabling 287 
Watch command 
Module window local menu 132 
Watches window local menu 107 
Watches command 100 
Watches window 26, 100-102 
local menu 701, 203 
maximum tiled size 284 
opening 100 
using 236, 243 
C tutorial 48 
Pascal tutorial 54 
watchpoints 716, 115, See also breakpoints 
C tutorial 48 
Pascal tutorial 54 
reloading programs and 97 
wildcards 
DOS 134, 327 
searching with 133, 208 
Window menu 45, 196 
opening 33 
window management and 33 
Window Pick command 33 
windows 16, 25-36 
active 37 
returning to 19 
bottom line in 38 
Breakpoints 26, 118-122 
closing 35 


Inspector See Inspector windows 
layout, saving 36, 73 
local menus and 22 
Log 27, 122-124, 200 
Module See Module window 
mouse support 31-32 
moving 34 
moving around in 208 
multiple 33, 132, 136, 183 
moving between 33 
Numeric Processor 29, 186-189, 201 
problems with 327 
opening 
duplicate 30 
new 26 
panes See panes 
problems with 28, 30, 323 
current program location and 86 
recovering last closed 35 
reducing to icon 32, 35 
Registers 28, 183, 202 
repainting 35, See also display updating 
resizing 32, 34 
saving layout 97 
single-line borders and 35 
Stack 27, 79-80, 203 
opening 77 
tiled 44 
maximum size 284 
tutorial 44 
Variables 27, 76-78, 203 
opening 77 
Watches See Watches windows 


Windows command (TDINST) 280 
word 168 


formatting 174, 177 
pointer chains 176-177 
read/writes 172 


temporarily 35 Word command 177 


_ ne a ee WordStar-style cursor-movement commands 
customizing 206, 288 


Dump 28, 182, 200 Write command 179 
Execution History 29, 86-89, 288 Write Word command 172 
opening 86 
File 27, 134-136, 200 
opening 132 X 
Hierarchy 29, 155, 202 XMS standard 249 
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Y —zi option (TASM) 63 


~y option (set overlay pool size) 68 ZIP files 10 
zoom box 32 
Z Zoom command 35 


zoom icon 32 
Zero command 773, 187 
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